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 1740b2c155..fd7ffd3ba5 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 @@ -13,9 +13,20 @@ generator client { } ``` -A generator determines which assets are created when you run the `prisma generate` command. The main property `provider` defines which **Prisma Client (language specific)** is created - currently, only `prisma-client-js` is available. Alternatively you can define any npm package that follows our generator specification. Additionally and optionally you can define a custom output folder for the generated assets with `output`. +A generator determines which assets are created when you run the `prisma generate` command. -## Prisma Client: `prisma-client-js` +There are two generators for Prisma Client: + +- `prisma-client-js`: Generates Prisma Client into `node_modules` +- `prisma-client` ([Early Access](/orm/more/releases#early-access)): Newer and more flexible version of `prisma-client-js` with ESM support; it outputs plain TypeScript code and _requires_ a custom `output` path + +Alternatively, you can configure any npm package that complies with our generator specification. + +## `prisma-client-js` + +The `prisma-client-js` is the default generator for Prisma ORM 6.X versions and before. It requires the `@prisma/client` npm package and generates Prisma Client into `node_modules`. + +### Field reference The generator for Prisma's JavaScript Client accepts multiple additional properties: @@ -26,13 +37,13 @@ The generator for Prisma's JavaScript Client accepts multiple additional propert generator client { provider = "prisma-client-js" previewFeatures = ["sample-preview-feature"] - binaryTargets = ["linux-musl"] + binaryTargets = ["debian-openssl-1.1.x"] // defaults to `"native"` } ``` ### Binary targets -Prisma Client JS (`prisma-client-js`) uses several [engines](https://github.com/prisma/prisma-engines). Engines are implemented in Rust and are used by Prisma Client in the form of executable, platform dependent engine files. Depending on which platform you are executing your code on, you need the correct file. "Binary targets" are used to define which files should be present for the target platform(s). +The `prisma-client-js` generator uses several [engines](https://github.com/prisma/prisma-engines). Engines are implemented in Rust and are used by Prisma Client in the form of executable, platform-dependent engine files. Depending on which platform you are executing your code on, you need the correct file. "Binary targets" are used to define which files should be present for the target platform(s). The correct file is particularly important when [deploying](/orm/prisma-client/deployment/deploy-prisma) your application to production, which often differs from your local development environment. @@ -42,7 +53,7 @@ The `native` binary target is special. It doesn't map to a concrete operating sy As an example, assume you're running **macOS** and you specify the following generator: -```prisma +```prisma file=prisma/schema.prisma generator client { provider = "prisma-client-js" binaryTargets = ["native"] @@ -55,6 +66,130 @@ If you use macOS ARM64 (`darwin-arm64`), then the binary file that was compiled > **Note**: The `native` binary target is the default. You can set it explicitly if you wish to include additional [binary targets](/orm/reference/prisma-schema-reference#binarytargets-options) for deployment to different environments. +## `prisma-client` (Early Access) + +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, including the query engine. + +Currently in [Early Access](/orm/more/releases#early-access), this generator ensures you can bundle your application code exactly the way you want, without relying on hidden or automatic behaviors. + +Here are the main differences compared to `prisma-client-js`: + +- Requires an `output` path; no “magic” generation into `node_modules` any more +- Supports ESM and CommonJS via the `moduleFormat` field +- More flexible thanks to additional fields +- Outputs plain TypeScript that's bundled just like the rest of your application code + +The `prisma-client` generator will become the new default with Prisma ORM v7. + +### Getting started + +Follow these steps to use the new `prisma-client` generator in your project. + +#### 1. Configure the `prisma-client` generator in `schema.prisma` + +Update your [`generator`](/orm/prisma-schema/overview/generators) block: + +```prisma file=prisma/schema.prisma +generator client { + //add-start + provider = "prisma-client" // Required + output = "../src/generated/prisma" // Required path + //add-end +} +``` + +The **`output` option is required** and tells Prisma ORM where to put the generated Prisma Client code. You can choose any location suitable for your project structure. For instance, if you have the following layout: + +```txt +. +├── package.json +├── prisma +│ └── schema.prisma +├── src +│ └── index.ts +└── tsconfig.json +``` + +Then `../src/generated/prisma` places the generated code in `src/generated/prisma` relative to `schema.prisma`. + +#### 2. Generate Prisma Client + +Generate Prisma Client by running: + +```bash +npx prisma generate +``` + +This generates the code for Prisma Client (including the query engine binary) into the specified `output` folder. + +#### 3. Exclude the generated directory from version control + +The new generator includes both the TypeScript client code _and_ the [query engine](/orm/more/under-the-hood/engines#the-query-engine-file). Including the query engine in version control can cause compatibility issues on different machines. To avoid this, add the generated directory to `.gitignore`: + +```bash file=.gitignore +# Keep the generated Prisma Client + query engine out of version control +/src/generated/prisma +``` + +:::note + +In the future, you can safely include the generated directory in version control when [Prisma ORM is fully transitioned from Rust to TypeScript](https://www.prisma.io/blog/rust-to-typescript-update-boosting-prisma-orm-performance?utm_source=docs&utm_medium=inline_text). + +::: + +#### 4. Use Prisma Client in your application + +After generating the Prisma Client, import the types from the path you specified: + +```ts file=src/index.ts +import { PrismaClient } from "./generated/prisma/client" + +const prisma = new PrismaClient() +``` + +Prisma Client is now ready to use in your project. + +### Field reference + +Use the following options in the `generator client { ... }` block. Only `output` is required. The other fields have defaults or are inferred from your environment and `tsconfig.json`. + +```prisma file=schema.prisma +generator client { + // Required + provider = "prisma-client" + output = "../src/generated/prisma" + + // Optional + runtime = "nodejs" + moduleFormat = "esm" + generatedFileExtension = "ts" + importFileExtension = "ts" +} +``` + +Below are the options for the `prisma-client` generator: + +| **Option** | **Default** | **Description** | +| ------------------------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `output` (**required**) | | Directory where Prisma Client is generated, e.g. `../src/generated/prisma`. | +| `runtime` | `nodejs` | Target runtime environment.
Supported values:
`nodejs` (alias `node`), `deno`, `bun`, `deno-deploy`, `workerd` (alias `cloudflare`), `edge-light` (alias `vercel`), `react-native`. | +| `moduleFormat` | Inferred from environment | Module format (`esm` or `cjs`). Determines whether `import.meta.url` or `__dirname` is used. | +| `generatedFileExtension` | `ts` | File extension for generated TypeScript files (`ts`, `mts`, `cts`). | +| `importFileExtension` | `ts` | File extension used in **import statements**. Can be `ts`, `mts`, `cts`, `js`, `mjs`, `cjs`, or empty (for bare imports). | + +### Limitations + +- **Namespace usage**: The generated code still relies on TypeScript features like `namespace`, which may cause incompatibility with certain runtime-only setups (e.g., Node.js 22+ without `--experimental-transform-types`). It remains fully compatible with standard runtimes, `tsx`, `ts-node`, and most bundlers. +- **No browser bundle**: There is currently no official browser build, and importing types or enums in frontend code is not supported. + +:::note + +Both limitations will be resolved soon in a future release. + +::: + ## Community generators :::note diff --git a/content/200-orm/200-prisma-client/000-setup-and-configuration/010-generating-prisma-client.mdx b/content/200-orm/200-prisma-client/000-setup-and-configuration/010-generating-prisma-client.mdx index e5e757de81..e85baa85cc 100644 --- a/content/200-orm/200-prisma-client/000-setup-and-configuration/010-generating-prisma-client.mdx +++ b/content/200-orm/200-prisma-client/000-setup-and-configuration/010-generating-prisma-client.mdx @@ -49,11 +49,11 @@ To generate and instantiate Prisma Client: 1. You can now [instantiate Prisma Client](/orm/prisma-client/setup-and-configuration/instantiate-prisma-client) in your code: - ```ts - import { PrismaClient } from 'app/generated/prisma/client' - const prisma = new PrismaClient() - // use `prisma` in your application to read and write data in your DB - ``` + ```ts + import { PrismaClient } from 'app/generated/prisma/client' + const prisma = new PrismaClient() + // use `prisma` in your application to read and write data in your DB + ``` > **Important**: You need to re-run the `prisma generate` command after every change that's made to your Prisma schema to update the generated Prisma Client code. @@ -61,36 +61,11 @@ Here is a graphical illustration of the typical workflow for generation of Prism ![Graphical illustration of the typical workflow for generation of Prisma Client](./prisma-client-generation-workflow.png) -## The `@prisma/client` npm package - -The `@prisma/client` npm package consists of two key parts: - -- The `@prisma/client` module itself, which only changes when you re-install the package -- The `.prisma/client` folder, which is the [default location](#using-a-custom-output-path) for the unique Prisma Client generated from your schema - -`@prisma/client/index.d.ts` exports `.prisma/client`: - -```ts -export * from '.prisma/client' -``` - -This means that you still import `@prisma/client` in your own `.ts` files: - -```ts -import { PrismaClient } from '@prisma/client' -``` - -Prisma Client is generated from your Prisma schema and is unique to your project. Each time you change the schema (for example, by performing a [schema migration](/orm/prisma-migrate)) and run `prisma generate`, Prisma Client's code changes: - -![The .prisma and @prisma folders](./prisma-client-node-module.png) - -The `.prisma` folder is unaffected by [pruning](https://docs.npmjs.com/cli/prune.html) in Node.js package managers. - ## The location of Prisma Client -:::danger +:::warning -We strongly recommend you define an output path. In Prisma ORM 6.6, not defining an output path will result in a warning. In Prisma ORM 7, the field will be required. +We strongly recommend you define a custom `output` path. In Prisma ORM version `6.6.0`, not defining an `output` path will result in a warning. In Prisma ORM 7, the field will be required. ::: @@ -116,3 +91,35 @@ To import the `PrismaClient` from a custom location (for example, from a file na ```ts import { PrismaClient } from './generated/client' ``` + +:::note + + +For improved compatibility with ECMAScript modules (ESM) and to ensure consistent behaviour of Prisma ORM across different Node.js runtimes, you can also use the [`prisma-client` generator](/orm/prisma-schema/overview/generators#prisma-client-early-access) (Preview). This generator is specifically designed to handle common challenges with module resolution and runtime variations, providing a smoother integration experience and less friction with bundlers. + +::: + +## The `@prisma/client` npm package + +The `@prisma/client` npm package consists of two key parts: + +- The `@prisma/client` module itself, which only changes when you re-install the package +- The `.prisma/client` folder, which is the [default location](#using-a-custom-output-path) for the unique Prisma Client generated from your schema + +`@prisma/client/index.d.ts` exports `.prisma/client`: + +```ts +export * from '.prisma/client' +``` + +This means that you still import `@prisma/client` in your own `.ts` files: + +```ts +import { PrismaClient } from '@prisma/client' +``` + +Prisma Client is generated from your Prisma schema and is unique to your project. Each time you change the schema (for example, by performing a [schema migration](/orm/prisma-migrate)) and run `prisma generate`, Prisma Client's code changes: + +![The .prisma and @prisma folders](./prisma-client-node-module.png) + +The `.prisma` folder is unaffected by [pruning](https://docs.npmjs.com/cli/prune.html) in Node.js package managers. \ No newline at end of file diff --git a/content/200-orm/500-reference/100-prisma-schema-reference.mdx b/content/200-orm/500-reference/100-prisma-schema-reference.mdx index 9c8c634416..ad4f40aeba 100644 --- a/content/200-orm/500-reference/100-prisma-schema-reference.mdx +++ b/content/200-orm/500-reference/100-prisma-schema-reference.mdx @@ -165,13 +165,18 @@ A `generator` block accepts the following fields: | Name | Required | Type | Description | | :-----------------| :----------------------- | :----------------------- | :----------------------- | -| `provider` | **Yes** | String (file path) or Enum (`prisma-client-js`) | Describes which [generator](/orm/prisma-schema/overview/generators) to use. This can point to a file that implements a generator or specify a built-in generator directly. | +| `provider` | **Yes** | String (file path) or Enum (`prisma-client-js` | `prisma-client`) | Describes which [generator](/orm/prisma-schema/overview/generators) to use. This can point to a file that implements a generator or specify a built-in generator directly. | | `output` | No* | String (file path) | Determines the location for the generated client, [learn more](/orm/prisma-client/setup-and-configuration/generating-prisma-client#using-a-custom-output-path). **Default**: `node_modules/.prisma/client` | | `previewFeatures` | No | List of Enums | Use intellisense to see list of currently available Preview features (`Ctrl+Space` in Visual Studio Code) **Default**: none | | | `engineType` | No | Enum (`library` or `binary`) | Defines the [query engine](/orm/more/under-the-hood/engines) type to download and use. **Default**: `library` | | `binaryTargets` | No | List of Enums (see below) | Specify the OS on which the Prisma Client will run to ensure compatibility of the [query engine](/orm/more/under-the-hood/engines). **Default**: `native` | -> * We recommend defining a custom output path, adding the path to `.gitignore`, and then making sure to run `prisma generate` via a custom build script or postinstall hook. + +:::note[important] + +We recommend defining a custom output path, adding the path to `.gitignore`, and then making sure to run `prisma generate` via a custom build script or postinstall hook. + +::: #### `binaryTargets` options diff --git a/content/200-orm/500-reference/500-preview-features/050-client-preview-features.mdx b/content/200-orm/500-reference/500-preview-features/050-client-preview-features.mdx index bc2be4e0cd..081cab5fc9 100644 --- a/content/200-orm/500-reference/500-preview-features/050-client-preview-features.mdx +++ b/content/200-orm/500-reference/500-preview-features/050-client-preview-features.mdx @@ -30,6 +30,7 @@ The following [Preview](/orm/more/releases#preview) feature flags are available | `typedSql` | [5.19.0](https://github.com/prisma/prisma/releases/tag/5.19.0) | [Submit feedback](https://github.com/prisma/prisma/discussions/25106) | | `strictUndefinedChecks` | [5.20.0](https://github.com/prisma/prisma/releases/tag/5.20.0) | [Submit feedback](https://github.com/prisma/prisma/discussions/25271) | | [`fullTextSearchPostgres`](/orm/prisma-client/queries/full-text-search) | [6.0.0](https://github.com/prisma/prisma/releases/tag/6.0.0) | [Submit feedback](https://github.com/prisma/prisma/issues/25773) | +| [`prisma-client`](/orm/prisma-schema/overview/generators#prisma-client-early-access) | [6.6.0](https://pris.ly/release/6.6.0) | [Submit feedback](https://github.com/prisma/prisma/issues/25773) | To enable a Preview feature, [add the feature flag to the `generator` block](#enabling-a-prisma-client-preview-feature) in your `schema.prisma` file. [Share your feedback on all Preview features on GitHub](https://github.com/prisma/prisma/issues/3108).