From 4ea26e331783c68b6147b2b1f24f5553adc390b3 Mon Sep 17 00:00:00 2001 From: Florian Goessler Date: Thu, 2 Oct 2025 10:37:32 +0200 Subject: [PATCH 1/9] docs: improve docs about prisma-client imports --- .../10-overview/03-generators.mdx | 129 +++++++++++++++--- 1 file changed, 111 insertions(+), 18 deletions(-) diff --git a/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx b/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx index 57c2ab6c98..0b66886323 100644 --- a/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx +++ b/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx @@ -237,23 +237,12 @@ Below are the options for the `prisma-client` generator: ::: -### Output splitting and importing types +### Importing Types -The `prisma-client-js` generator used to generate all typings into a single `index.d.ts` file, which could lead to [slowing down editors](https://github.com/prisma/prisma/issues/4807) (e.g. breaking auto-complete) with large schemas. +The new `prisma-client` generator creates individual `.ts` files which allow for a more fine granular import of types. This can improve compile and typecheck performance and be useful for tree-shacking, too. +You can still use the top level barrel files that export all types through a single import. -The new `prisma-client` generator now splits the generated Prisma Client library into multiple files and thus avoids the problems of a single, large output file. - -**Before** (`prisma-client-js`) - -``` -generated/ -└── prisma - ├── client.ts - ├── index.ts # -> this is split into multiple files in 6.7.0 - └── libquery_engine-darwin.dylib.node -``` - -**After** (`prisma-client`) +The overall structure of the generated output looks like this: ``` generated/ @@ -263,15 +252,119 @@ generated/ ├── commonInputTypes.ts ├── enums.ts ├── internal - │ ├── class.ts - │ ├── prismaNamespace.ts - │ └── prismaNamespaceBrowser.ts + │ ├── ... ├── models │ ├── Post.ts │ └── User.ts └── models.ts ``` +#### `client.ts` + +For use in your server code. + +- Provides access to the `PrismaClient` instance and all model and utility types. +- Provides best compatibility with the `prisma-client-js` generated output. +- Contains transitive dependencies on server only packages so cannot be used in browser contexts. + +Example: +``` +import { Prisma, type Post, PrismaClient } from `./generated/prisma/client` +``` + +#### `browser.ts` + +For using types in your frontend aka browser code. + +- Contains no transitive dependencies on node.js or other server only packages. +- Contains no real `PrismaClient`. +- Contains all model and enum types and values. +- Provides access to various utilities like `Prisma.JsonNull` and `Prisma.Decimal`. + +:::note + +The old `prisma-client-js` generator created a node_modules package and used export maps to dynamically provide a browser compatible export of the generated prisma client. +As the new `prisma-client` generator creates direct TypeScript source code and no package.json anymore, this approach is not possible. +Hence you need to be explicit about your imports and whether things run on server or client! + +You can still wrap the generated code in a package and use a similar approach on your own. + +::: + +Example: +``` +import { Prisma, type Post } from `./generated/prisma/browser` +``` + +#### `enums.ts` + +Isolated access to user defined enum types and values. + +- Contains no transitive dependencies and is very slim. +- Can be used on backend and frontend. +- Prefer this for optimal tree shacking and typecheck performance when accessing enums. + +Example: +``` +import { MyEnum } from `./generated/prisma/enums` +``` + +#### `models.ts` + +Isolated access to all model types. + +- Can be used on backend and frontend. +- Contains all models including their derived utility types like `WhereInput` or `UpdateInput>. + +:::note + +Plain model types are exposed here as `Model` (e.g. `PostModel`). This is in contrast to the exposed name in `client.ts` and `browser.ts` which is simply `` (e.g. `Post`). + +This is necessary due to internal constraints to avoid potential naming conflicts with internal types. + +::: + +Example: +``` +import type { UserModel, PostModel, PostWhereInput, UserUpdateInput } from `./generated/prisma/models` +``` + + +#### `models/.ts + +Isolated access to the types for an individual model. + +- Can be used on backend and frontend. +- Contains the models including its derived utility types like `WhereInput` or `UpdateInput>. + +:::note + +The plain model type is exposed here as `Model` (e.g. `PostModel`). + +::: + +Example: +``` +import type { UserModel, UserWhereInput, UserUpdateInput } from `./generated/prisma/models/User` +``` + + +#### `commonInputTypes.ts` + +Provides shared utility types that you should rarely directly need. + +Example: +``` +import type { IntFilter } from `./generated/prisma/commonInputTypes` +``` + +#### `internal/*` + +:warning: Do not directly import from these files! They are not part of the stable API of the generated code and can change at any time in breaking ways. + +Usually anything you might need from there is exposed via `browser.ts` or `client.ts` under the `Prisma` namespace. + + ### Breaking changes from `prisma-client-js` - Requires an `output` path on the `generator` block From c71e8194846a5321a4c1b358e2f8858ecd312a7d Mon Sep 17 00:00:00 2001 From: Florian Goessler Date: Thu, 2 Oct 2025 10:40:11 +0200 Subject: [PATCH 2/9] docs: add note about when browser.ts was added --- content/200-orm/100-prisma-schema/10-overview/03-generators.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx b/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx index 0b66886323..ffb780fba4 100644 --- a/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx +++ b/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx @@ -280,6 +280,7 @@ For using types in your frontend aka browser code. - Contains no real `PrismaClient`. - Contains all model and enum types and values. - Provides access to various utilities like `Prisma.JsonNull` and `Prisma.Decimal`. +- Available since `v6.16.0`. :::note From c64eaa0903b6eabfae4806d05cb9c1d44abbb3fc Mon Sep 17 00:00:00 2001 From: Nikolas Date: Tue, 7 Oct 2025 08:37:19 +0200 Subject: [PATCH 3/9] Update content/200-orm/100-prisma-schema/10-overview/03-generators.mdx --- content/200-orm/100-prisma-schema/10-overview/03-generators.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx b/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx index ffb780fba4..bc7252e583 100644 --- a/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx +++ b/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx @@ -237,7 +237,7 @@ Below are the options for the `prisma-client` generator: ::: -### Importing Types +### Importing types The new `prisma-client` generator creates individual `.ts` files which allow for a more fine granular import of types. This can improve compile and typecheck performance and be useful for tree-shacking, too. You can still use the top level barrel files that export all types through a single import. From 9370375549e83a5a8c87f2944b2493e7eb812008 Mon Sep 17 00:00:00 2001 From: Nikolas Date: Tue, 7 Oct 2025 09:49:57 +0200 Subject: [PATCH 4/9] Update 03-generators.mdx --- content/200-orm/100-prisma-schema/10-overview/03-generators.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx b/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx index bc7252e583..8096da81d9 100644 --- a/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx +++ b/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx @@ -92,7 +92,7 @@ If you use macOS ARM64 (`darwin-arm64`), then the binary file that was compiled The new `prisma-client` generator offers greater control and flexibility when using Prisma ORM across different JavaScript environments (such as ESM, Bun, Deno, ...). -It generates Prisma Client into a custom directory in your application's codebase that's specified via the `output` field on the `generator` block. This gives you full visibility and control over the generated code. It also [splits](#output-splitting-and-importing-types) the generated Prisma Client library into multiple files. +It generates Prisma Client into a custom directory in your application's codebase that's specified via the `output` field on the `generator` block. This gives you full visibility and control over the generated code. It also [splits](#importing-types) the generated Prisma Client library into multiple files. This generator ensures you can bundle your application code exactly the way you want, without relying on hidden or automatic behaviors. From 83fb9b4aae0f6007bc933d9aeb1dd73a783c382a Mon Sep 17 00:00:00 2001 From: Nikolas Burk Date: Tue, 7 Oct 2025 10:05:07 +0200 Subject: [PATCH 5/9] polish prisma-client generator import docs --- .../10-overview/03-generators.mdx | 40 +++++++++++-------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx b/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx index 8096da81d9..b21d143ed1 100644 --- a/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx +++ b/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx @@ -265,35 +265,35 @@ For use in your server code. - Provides access to the `PrismaClient` instance and all model and utility types. - Provides best compatibility with the `prisma-client-js` generated output. -- Contains transitive dependencies on server only packages so cannot be used in browser contexts. +- Contains transitive dependencies on server only-packages, so cannot be used in browser contexts. Example: -``` + +```ts import { Prisma, type Post, PrismaClient } from `./generated/prisma/client` ``` #### `browser.ts` -For using types in your frontend aka browser code. +For using types in your frontend (i.e. code that runs in the browser). -- Contains no transitive dependencies on node.js or other server only packages. -- Contains no real `PrismaClient`. +- Contains no transitive dependencies on Node.js or other server-only packages. +- Contains no real `PrismaClient` constructor. - Contains all model and enum types and values. - Provides access to various utilities like `Prisma.JsonNull` and `Prisma.Decimal`. - Available since `v6.16.0`. :::note -The old `prisma-client-js` generator created a node_modules package and used export maps to dynamically provide a browser compatible export of the generated prisma client. -As the new `prisma-client` generator creates direct TypeScript source code and no package.json anymore, this approach is not possible. -Hence you need to be explicit about your imports and whether things run on server or client! +The old `prisma-client-js` generator created a `node_modules` package and used export maps to dynamically provide a browser compatible export of the generated Prisma Client library. As the new `prisma-client` generator creates direct TypeScript source code and no `package.json` file anymore, this approach is not possible. Hence you need to be explicit about your imports and whether things run on server or client! -You can still wrap the generated code in a package and use a similar approach on your own. +You can still wrap the generated code in a package and use a similar approach as with `prisma-client-js` on your own. ::: Example: -``` + +```ts import { Prisma, type Post } from `./generated/prisma/browser` ``` @@ -306,7 +306,8 @@ Isolated access to user defined enum types and values. - Prefer this for optimal tree shacking and typecheck performance when accessing enums. Example: -``` + +```ts import { MyEnum } from `./generated/prisma/enums` ``` @@ -315,7 +316,7 @@ import { MyEnum } from `./generated/prisma/enums` Isolated access to all model types. - Can be used on backend and frontend. -- Contains all models including their derived utility types like `WhereInput` or `UpdateInput>. +- Contains all models including their derived utility types like `WhereInput` or `UpdateInput>`. :::note @@ -331,12 +332,12 @@ import type { UserModel, PostModel, PostWhereInput, UserUpdateInput } from `./ge ``` -#### `models/.ts +#### `models/.ts` Isolated access to the types for an individual model. - Can be used on backend and frontend. -- Contains the models including its derived utility types like `WhereInput` or `UpdateInput>. +- Contains the models including its derived utility types like `WhereInput` or `UpdateInput>`. :::note @@ -345,7 +346,8 @@ The plain model type is exposed here as `Model` (e.g. `PostModel`). ::: Example: -``` + +```ts import type { UserModel, UserWhereInput, UserUpdateInput } from `./generated/prisma/models/User` ``` @@ -355,16 +357,20 @@ import type { UserModel, UserWhereInput, UserUpdateInput } from `./generated/pri Provides shared utility types that you should rarely directly need. Example: -``` + +```ts import type { IntFilter } from `./generated/prisma/commonInputTypes` ``` #### `internal/*` -:warning: Do not directly import from these files! They are not part of the stable API of the generated code and can change at any time in breaking ways. +:::warnin + +Do not directly import from these files! They are not part of the stable API of the generated code and can change at any time in breaking ways. Usually anything you might need from there is exposed via `browser.ts` or `client.ts` under the `Prisma` namespace. +::: ### Breaking changes from `prisma-client-js` From 1d7ad3b95c6020e0eba46daf9389b14436959f86 Mon Sep 17 00:00:00 2001 From: Nikolas Date: Tue, 7 Oct 2025 10:11:59 +0200 Subject: [PATCH 6/9] Update content/200-orm/100-prisma-schema/10-overview/03-generators.mdx Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- content/200-orm/100-prisma-schema/10-overview/03-generators.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx b/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx index b21d143ed1..054e500c21 100644 --- a/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx +++ b/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx @@ -364,7 +364,7 @@ import type { IntFilter } from `./generated/prisma/commonInputTypes` #### `internal/*` -:::warnin +:::warning Do not directly import from these files! They are not part of the stable API of the generated code and can change at any time in breaking ways. From c25dc35350bef91c909520afbd7636eb604ac012 Mon Sep 17 00:00:00 2001 From: Nikolas Date: Tue, 7 Oct 2025 10:12:17 +0200 Subject: [PATCH 7/9] Update content/200-orm/100-prisma-schema/10-overview/03-generators.mdx Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- content/200-orm/100-prisma-schema/10-overview/03-generators.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx b/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx index 054e500c21..c31e61ea21 100644 --- a/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx +++ b/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx @@ -239,7 +239,7 @@ Below are the options for the `prisma-client` generator: ### Importing types -The new `prisma-client` generator creates individual `.ts` files which allow for a more fine granular import of types. This can improve compile and typecheck performance and be useful for tree-shacking, too. +The new `prisma-client` generator creates individual `.ts` files which allow for a more fine granular import of types. This can improve compile and typecheck performance and be useful for tree-shaking, too. You can still use the top level barrel files that export all types through a single import. The overall structure of the generated output looks like this: From e8b9d286aa2bb6fb3f89a074affcf8b19aeba53f Mon Sep 17 00:00:00 2001 From: Nikolas Burk Date: Tue, 7 Oct 2025 10:14:32 +0200 Subject: [PATCH 8/9] fix quotes in import snippets --- .../10-overview/03-generators.mdx | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx b/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx index b21d143ed1..b51ccdc2cd 100644 --- a/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx +++ b/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx @@ -270,7 +270,7 @@ For use in your server code. Example: ```ts -import { Prisma, type Post, PrismaClient } from `./generated/prisma/client` +import { Prisma, type Post, PrismaClient } from "./generated/prisma/client" ``` #### `browser.ts` @@ -294,7 +294,7 @@ You can still wrap the generated code in a package and use a similar approach as Example: ```ts -import { Prisma, type Post } from `./generated/prisma/browser` +import { Prisma, type Post } from "./generated/prisma/browser" ``` #### `enums.ts` @@ -308,7 +308,7 @@ Isolated access to user defined enum types and values. Example: ```ts -import { MyEnum } from `./generated/prisma/enums` +import { MyEnum } from "./generated/prisma/enums" ``` #### `models.ts` @@ -327,8 +327,9 @@ This is necessary due to internal constraints to avoid potential naming conflict ::: Example: -``` -import type { UserModel, PostModel, PostWhereInput, UserUpdateInput } from `./generated/prisma/models` + +```ts +import type { UserModel, PostModel, PostWhereInput, UserUpdateInput } from "./generated/prisma/models" ``` @@ -348,7 +349,7 @@ The plain model type is exposed here as `Model` (e.g. `PostModel`). Example: ```ts -import type { UserModel, UserWhereInput, UserUpdateInput } from `./generated/prisma/models/User` +import type { UserModel, UserWhereInput, UserUpdateInput } from "./generated/prisma/models/User" ``` @@ -359,12 +360,12 @@ Provides shared utility types that you should rarely directly need. Example: ```ts -import type { IntFilter } from `./generated/prisma/commonInputTypes` +import type { IntFilter } from "./generated/prisma/commonInputTypes" ``` #### `internal/*` -:::warnin +:::warning Do not directly import from these files! They are not part of the stable API of the generated code and can change at any time in breaking ways. From 69de745afb40c6c2baa650763bb2dbecbed5653d Mon Sep 17 00:00:00 2001 From: Nikolas Burk Date: Tue, 7 Oct 2025 10:25:20 +0200 Subject: [PATCH 9/9] minor fix --- .../200-orm/100-prisma-schema/10-overview/02-data-sources.mdx | 4 ---- .../200-orm/100-prisma-schema/10-overview/03-generators.mdx | 2 +- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/content/200-orm/100-prisma-schema/10-overview/02-data-sources.mdx b/content/200-orm/100-prisma-schema/10-overview/02-data-sources.mdx index 31d932e70d..862dea32ac 100644 --- a/content/200-orm/100-prisma-schema/10-overview/02-data-sources.mdx +++ b/content/200-orm/100-prisma-schema/10-overview/02-data-sources.mdx @@ -4,8 +4,6 @@ metaTitle: 'Data sources (Reference)' metaDescription: 'Data sources enable Prisma to connect to your database. This page explains how to configure data sources in your Prisma schema.' --- - - A data source determines how Prisma ORM connects to your database, and is represented by the [`datasource`](/orm/reference/prisma-schema-reference#datasource) block in the Prisma schema. The following data source uses the `postgresql` provider and includes a connection URL: ```prisma @@ -22,8 +20,6 @@ A Prisma schema can only have _one_ data source. However, you can: > **Note**: Multiple provider support was removed in 2.22.0. Please see [Deprecation of provider array notation](https://github.com/prisma/prisma/issues/3834) for more information. - - ## Securing database connections Some data source `provider`s allow you to configure your connection with SSL/TLS, and provide parameters for the `url` to specify the location of certificates. diff --git a/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx b/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx index 6e8aa29a5b..843aef49f0 100644 --- a/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx +++ b/content/200-orm/100-prisma-schema/10-overview/03-generators.mdx @@ -303,7 +303,7 @@ Isolated access to user defined enum types and values. - Contains no transitive dependencies and is very slim. - Can be used on backend and frontend. -- Prefer this for optimal tree shacking and typecheck performance when accessing enums. +- Prefer this for optimal tree shaking and typecheck performance when accessing enums. Example: