# contract emit (/docs/cli/contract-emit)

> For the complete Prisma documentation index, see [llms.txt](https://www.prisma.io/docs/llms.txt). A markdown version of any docs page is available by appending `.md` to its URL.

Emit Prisma ORM contract artifacts.

Location: CLI > contract emit

`contract emit` reads your contract source (TypeScript or Prisma schema) and writes the generated artifacts used by the runtime, verification, and migration tooling.

The command is offline. It does not need a database connection.

A Prisma schema source can be one `.prisma` file or a glob that matches several files; see [Split the schema across several files](https://www.prisma.io/docs/cli/configuration#split-the-schema-across-several-files). `contract emit` reads only the `.prisma` files whose first line is `// use prisma-8`, and skips any other file without a warning. When no file starts with that line, it fails with `CONTRACT.SOURCE_LOAD_FAILED` and reports the problem with the code `PSL_NO_OPTED_IN_SCHEMA_FILES`.

## Usage [#usage]

  

#### bun

```bash
bunx prisma contract emit
```

#### pnpm

```bash
pnpm prisma contract emit
```

#### yarn

```bash
yarn prisma contract emit
```

#### npm

```bash
npx prisma contract emit
```

## Options [#options]

| Option                | What it does                                                          |
| --------------------- | --------------------------------------------------------------------- |
| `--output-path <dir>` | Writes `contract.json` and `contract.d.ts` into a specific directory. |
| `--config <path>`     | Read this config file instead of `./prisma.config.ts`.                |
| `--json`              | Prints a machine-readable result.                                     |

## What it creates [#what-it-creates]

The command emits:

* `contract.json`, the canonical machine-readable contract
* `contract.d.ts`, the generated TypeScript contract declarations

Do not edit these files by hand. Re-run `contract emit` after changing the contract source or extension pack list. The first emit after you upgrade from a release before `8.0.0-rc.12` reorders the entries in `contract.d.ts` to follow the order in `contract.json`, which needs no change to your code. The first emit after you upgrade from a release before `8.0.0-rc.13` renames two keys in `contract.json`: each generated default under `execution.mutations.defaults` names its target as `entry` and `field` instead of `table` and `column`. The client refuses a contract that has the old keys, so run `contract emit` after you upgrade. `contract emit` does not rewrite the contracts stored under `migrations/`, such as the snapshots in `migrations/snapshots/`. To rename the keys in them, download the [`rename-execution-ref-keys` script](https://github.com/prisma/orm/blob/v8.0.0-rc.15/skills/prisma-8/upgrading/app/upgrades/8.0.0-rc.12-to-8.0.0-rc.13/scripts/execution-ref-entry-field/rename-execution-ref-keys.ts) into your project root and run it there:

```bash title="Terminal"
curl -O https://raw.githubusercontent.com/prisma/orm/v8.0.0-rc.15/skills/prisma-8/upgrading/app/upgrades/8.0.0-rc.12-to-8.0.0-rc.13/scripts/execution-ref-entry-field/rename-execution-ref-keys.ts
npx tsx rename-execution-ref-keys.ts
```

The script renames `table` to `entry` and `column` to `field` in each `ref` under `execution.mutations.defaults`, in every `.json` and `.d.ts` file under a `migrations/` folder. It leaves each `executionHash` as it is, and a second run changes nothing. Pass `--check` to list the files it would change without writing them.

Since `8.0.0-rc.15`, each SQL column in `contract.json` stores its data type id, such as `"dataType": "pg/text"`, in place of `nativeType`, and the client refuses a contract in the old format. When you upgrade from a release before `8.0.0-rc.15`, upgrade every extension that ships migrations, such as pgvector and PostGIS, in the same step. Then, before the first emit, run the [`data-type-in-contract` script](https://github.com/prisma/orm/blob/v8.0.0-rc.15/skills/prisma-8/upgrading/app/upgrades/8.0.0-rc.14-to-8.0.0-rc.15/scripts/data-type-in-contract/data-type-in-contract.ts) in your project root, and sign every database with [`db sign`](https://www.prisma.io/docs/cli/db-sign):

```bash title="Terminal"
curl -O https://raw.githubusercontent.com/prisma/orm/v8.0.0-rc.15/skills/prisma-8/upgrading/app/upgrades/8.0.0-rc.14-to-8.0.0-rc.15/scripts/data-type-in-contract/data-type-in-contract.ts
node data-type-in-contract.ts
npx prisma db sign --db "$DATABASE_URL"
```

The script runs on any Node.js version Prisma ORM supports: 22.18 or newer on the 22 line, 24.11 or newer on the 24 line, or 26 or newer. It rewrites every contract, snapshot, migration, ref, `migration.ts`, and `contract.d.ts` in the project, and every storage hash changes once. Until a database is signed, `db migrate` refuses with `MIGRATION.MARKER_MISMATCH`. Commit your work before you run it, so you can review its changes.

When you upgrade from a release before `8.0.0-rc.19`, run `contract emit` again, because the files an earlier release wrote do not work with this one. A SQL `contract.d.ts` from an earlier release no longer compiles. The CLI refuses every older MongoDB `contract.json`, and some older PostgreSQL ones, with `CONTRACT.VALIDATION_FAILED`.

Then look at the `storageHash` value in `contract.json`. It identifies the tables and columns your contract describes, and `db sign` records it in each database. If the new emit changed it, run [`db sign`](https://www.prisma.io/docs/cli/db-sign) against every database that uses the contract, such as development, staging, and production. Until you do, `db migrate` fails with `MIGRATION.MARKER_MISMATCH` and `db verify` fails with `CONTRACT.MARKER_MISMATCH`, because the database still records the old value. The [upgrade instructions](https://github.com/prisma/orm/blob/v8.0.0-rc.19/skills/prisma-8/upgrading/app/upgrades/8.0.0-rc.18-to-8.0.0-rc.19/) include scripts that update the copies of the contract stored under `migrations/`.

When the contract source cannot be read, the command fails with `CONTRACT.SOURCE_LOAD_FAILED` and prints each finding, meaning each problem it found in the source, with the file and line where it knows them. In `--json` output, the findings are the entries of the `envelope.diagnostics` array in the final `result` event, next to `envelope.error`. Each entry has a `code`, a `summary`, and, where known, `where.path` and `where.line`. If an entry's `code` is `CONTRACT.SOURCE_DIAGNOSTIC`, the code of the specific problem, such as `PSL_NO_OPTED_IN_SCHEMA_FILES`, is in its `meta.code`.

A warning in the contract source, such as `PSL_DEPRECATED_SCALAR_NAME` for a MongoDB scalar type name that is deprecated, does not stop the command. It is reported as a diagnostic whose `severity` is `warn`, and the command still writes both files. In `--json` output, the warning is an entry of `envelope.diagnostics` in the final `result` event, with `code` set to `CONTRACT.SOURCE_DIAGNOSTIC` and the warning's own code in `meta.code`.

## Run it automatically [#run-it-automatically]

In development, a Vite plugin runs `contract emit` for you: once when the dev server starts, and again whenever the contract source or `prisma.config.ts` changes. It needs Vite 7 or 8, and comes with your database package, so there is nothing to install:

```typescript title="vite.config.ts"
import { defineConfig } from "vite";
import { prismaVitePlugin } from "@prisma/orm-postgres/vite-plugin-contract-emit";

export default defineConfig({
  plugins: [prismaVitePlugin()],
});
```

On MongoDB, import it from `@prisma/orm-mongo/vite-plugin-contract-emit`. The plugin reads `prisma.config.ts` from the Vite root; pass another path as the first argument, `prismaVitePlugin("config/prisma.config.ts")`. A second argument takes `debounceMs` (how long to wait after a change before emitting, 150 by default) and `logLevel` (`"silent"`, `"info"`, or `"debug"`). The dev server prints one line per emit:

```text
[prisma-vite-plugin-contract-emit] Emitted contract (storageHash: ab5014a0...)
```

An emit that fails shows in Vite's error overlay. The plugin does nothing in a production build, so builds and CI still run the command themselves. With any other bundler, or for a build, add the command as a `prebuild` script, which npm, pnpm, and yarn run before `build`:

```json title="package.json (excerpt)"
{
  "scripts": {
    "prebuild": "prisma contract emit",
    "build": "next build"
  }
}
```

## Examples [#examples]

  

#### bun

```bash
bunx prisma contract emit
bunx prisma contract emit --output-path ./generated
bunx prisma contract emit --json
```

#### pnpm

```bash
pnpm prisma contract emit
pnpm prisma contract emit --output-path ./generated
pnpm prisma contract emit --json
```

#### yarn

```bash
yarn prisma contract emit
yarn prisma contract emit --output-path ./generated
yarn prisma contract emit --json
```

#### npm

```bash
npx prisma contract emit
npx prisma contract emit --output-path ./generated
npx prisma contract emit --json
```

## Next steps [#next-steps]

After emitting, choose the database workflow:

* use [`db init`](https://www.prisma.io/docs/cli/db-init) for first-time bootstrap
* use [`db update`](https://www.prisma.io/docs/cli/db-update) for direct reconciliation
* use [`migration plan`](https://www.prisma.io/docs/cli/migration-plan) for checked-in migrations
* use [`db verify`](https://www.prisma.io/docs/cli/db-verify) to check drift

## Related pages

- [`auth`](https://www.prisma.io/docs/cli/auth): Sign in to your Prisma account from the CLI, sign out, and manage workspace sessions.
- [`branch`](https://www.prisma.io/docs/cli/branch): List platform branches for a project.
- [`bucket`](https://www.prisma.io/docs/cli/bucket): Create and manage object-store buckets.
- [`Configuration`](https://www.prisma.io/docs/cli/configuration): Configure Prisma ORM CLI commands with prisma.config.ts and global flags.
- [`contract infer`](https://www.prisma.io/docs/cli/contract-infer): Infer a starter contract from an existing database.