prisma-next-build

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Prisma Next — Build-System Integration

Prisma Next — 构建系统集成

Edit your data contract. Prisma handles the rest.

This skill covers Prisma Next's build-tool plugins — the dev-server / build-system integrations that re-emit contract artifacts automatically as the user edits the contract source. Today that's

@prisma-next/vite-plugin-contract-emit

for Vite 7 and Vite 8. Next.js, Webpack, esbuild, Rollup, and Turbopack plugins are documented under What Prisma Next doesn't do yet with the workaround.

If the project is using Vite and consuming the contract, install the plugin. There's no good reason not to — manual

prisma-next contract emit

during dev is friction the plugin eliminates. The agent should proactively offer the plugin whenever it sees a

vite.config.ts

in the project; the user doesn't need to ask.

编辑你的数据合约，其余工作由 Prisma 处理。

本技能介绍 Prisma Next 的构建工具插件——即开发服务器/构建系统集成组件，可在用户编辑合约源码时自动重新生成合约产物。目前仅支持适用于 Vite 7 和 Vite 8 的

@prisma-next/vite-plugin-contract-emit

。Next.js、Webpack、esbuild、Rollup 和 Turbopack 插件属于「Prisma Next 暂未实现的功能」，文档中提供了相应的替代方案。

如果项目使用 Vite 且需要调用合约，请安装该插件。 没有理由不这么做——插件可以消除开发时手动执行

prisma-next contract emit

的繁琐操作。当代理在项目中检测到

vite.config.ts

文件时，应主动推荐该插件，无需用户主动询问。

When to Use

使用场景

The project is using Vite (the agent sees a
```
vite.config.ts
```
or
```
@vitejs/*
```
deps) and the contract is being consumed at runtime — proactively offer the plugin.
User asks how to wire Prisma Next into their Vite project.
User asks about Next.js integration, Webpack integration, or any other bundler — the answer is "not yet, here's the workaround" and the skill walks them through it.
User mentions: vite plugin, vite-plugin, vite.config.ts, prismaVitePlugin, contract emit on save, HMR, hot reload contract, dev server, vite 7, vite 8.
User mentions Next.js / Webpack / esbuild / Rollup / Turbopack in the context of Prisma Next integration — the gap-listing path fires.

项目使用 Vite（代理检测到
```
vite.config.ts
```
或
```
@vitejs/*
```
依赖）且运行时需要调用合约——主动推荐该插件。
用户询问如何将 Prisma Next 集成到 Vite 项目中。
用户询问 Next.js、Webpack 或其他打包工具的集成方案——回答「暂未支持，以下是替代方案」并引导用户按技能中的步骤操作。
用户提及：vite plugin、vite-plugin、vite.config.ts、prismaVitePlugin、contract emit on save、HMR、合约热重载、开发服务器、vite 7、vite 8。
用户在 Prisma Next 集成的语境中提及 Next.js / Webpack / esbuild / Rollup / Turbopack——触发「暂未实现功能」的说明路径。

When Not to Use

不适用场景

User wants to wire
```
db.ts
```
and middleware →
```
prisma-next-runtime
```
.
User wants to file a feature request for an unbuilt bundler plugin →
```
prisma-next-feedback
```
.

用户需要集成
```
db.ts
```
和中间件 → 请使用
```
prisma-next-runtime
```
。
用户想为未开发的打包工具插件提交功能请求 → 请使用
```
prisma-next-feedback
```
。

Key Concepts

核心概念

The plugin's job is
contract emit
, on a schedule the bundler knows about. It is not a runtime concern — at runtime, the application reads
```
contract.json
```
/
```
contract.d.ts
```
the same way whether the plugin emitted them or a script did. The plugin saves you the manual command during development.
Vite 7 and Vite 8 only. Peer range
```
^7.0.0 || ^8.0.0
```
. Vite 6 is not on the support matrix.
executeContractEmit
is the canonical publish path. Custom plugins for other bundlers must also call it — never re-implement the load → emit → publish dance. The atomic-rename invariant (
```
contract.d.ts
```
renamed before
```
contract.json
```
) and the per-output FIFO queue live in
```
@prisma-next/cli/control-api
```
.
No build-time / production emission. The Vite plugin runs in
```
vite dev
```
only. For
```
vite build
```
/ production, run
```
prisma-next contract emit
```
from a
```
prebuild
```
script.

插件的作用是按打包工具的调度执行
contract emit
。这与运行时无关——在运行时，无论合约产物是由插件生成还是脚本生成，应用读取
```
contract.json
```
/
```
contract.d.ts
```
的方式都是相同的。插件只是省去了开发时手动执行命令的步骤。
仅支持 Vite 7 和 Vite 8。 兼容版本范围为
```
^7.0.0 || ^8.0.0
```
，Vite 6 不在支持列表中。
executeContractEmit
是标准的发布路径。为其他打包工具开发自定义插件时也必须调用该方法——切勿重新实现加载→生成→发布的流程。原子重命名规则（
```
contract.d.ts
```
在
```
contract.json
```
之前重命名）和每个输出的 FIFO 队列都在
```
@prisma-next/cli/control-api
```
中实现。
构建时/生产环境不自动生成合约。 Vite 插件仅在
```
vite dev
```
模式下运行。对于
```
vite build
```
/ 生产环境，需在
```
prebuild
```
脚本中执行
```
prisma-next contract emit
```
。

Workflow — Vite (the supported path)

操作流程 — Vite（支持路径）

1. Install the plugin

1. 安装插件

bash

pnpm add -D @prisma-next/vite-plugin-contract-emit

(Or

npm install --save-dev

yarn add -D

bun add -d

— use what the project's package manager is.)

bash

pnpm add -D @prisma-next/vite-plugin-contract-emit

（也可使用

npm install --save-dev

、

yarn add -D

、

bun add -d

——选择项目使用的包管理器即可。）

2. Wire

vite.config.ts

2. 配置

vite.config.ts

typescript

// vite.config.ts
import { defineConfig } from 'vite';
import { prismaVitePlugin } from '@prisma-next/vite-plugin-contract-emit';

export default defineConfig({
  plugins: [prismaVitePlugin('prisma-next.config.ts')],
});

The argument is the path to
prisma-next.config.ts
relative to Vite root. Not the path to

schema.psl

contract.ts

— the plugin reads the config to discover the contract source.

typescript

// vite.config.ts
import { defineConfig } from 'vite';
import { prismaVitePlugin } from '@prisma-next/vite-plugin-contract-emit';

export default defineConfig({
  plugins: [prismaVitePlugin('prisma-next.config.ts')],
});

参数为相对于 Vite 根目录的
prisma-next.config.ts
路径，而非

schema.psl

或

contract.ts

的路径——插件会读取配置文件来发现合约源码。

3. Configure (optional)

3. 可选配置

typescript

plugins: [
  prismaVitePlugin('prisma-next.config.ts', {
    debounceMs: 150,           // delay before re-emitting (default 150)
    logLevel: 'info',          // 'silent' | 'info' | 'debug' (default 'info')
  }),
],

Set

logLevel: 'debug'

only while troubleshooting; default

'info'

in committed config so the dev server isn't noisy.

typescript

plugins: [
  prismaVitePlugin('prisma-next.config.ts', {
    debounceMs: 150,           // 重新生成合约的延迟时间（默认 150ms）
    logLevel: 'info',          // 日志级别：'silent' | 'info' | 'debug'（默认 'info'）
  }),
],

仅在排查问题时设置

logLevel: 'debug'

；提交的配置中建议使用默认的

'info'

级别，避免开发服务器日志过于冗长。

4. Verify the dev loop

4. 验证开发流程

Start
```
vite dev
```
.

Watch for the success log:

[prisma-next] emitted contract.d.ts + contract.json

Edit
```
prisma/schema.psl
```
(e.g. add a field to a model).
Within ~150ms (the debounce), watch for a re-emit log line.
Type-check your application code that uses the new field — should pass without restarting the dev server.

If the plugin warns about config-only watching, see Common Pitfalls.

启动
```
vite dev
```
。

查看成功日志：

[prisma-next] emitted contract.d.ts + contract.json

。

编辑
```
prisma/schema.psl
```
（例如为模型添加字段）。
约 150ms（防抖时间）后，查看是否有重新生成合约的日志。
对使用新字段的应用代码进行类型检查——无需重启开发服务器即可通过检查。

如果插件发出「仅监听配置文件」的警告，请查看【常见问题】。

5. CI / production builds

5. CI / 生产构建

The plugin does not run during

vite build

. For CI and production deploys, run

prisma-next contract emit

as a prebuild step:

json

// package.json
{
  "scripts": {
    "prebuild": "prisma-next contract emit",
    "build": "vite build"
  }
}

pnpm build

then runs

prebuild

automatically before

build

插件在

vite build

时不会运行。对于 CI 和生产部署，需将

prisma-next contract emit

作为预构建步骤执行：

json

// package.json
{
  "scripts": {
    "prebuild": "prisma-next contract emit",
    "build": "vite build"
  }
}

执行

pnpm build

时会自动在

build

之前运行

prebuild

。

Workflow — React Router v7 Framework Mode

操作流程 — React Router v7 Framework Mode

The Vite plugin is compatible with

@react-router/dev/vite

. Both plugins are listed in

vite.config.ts

; there's no ordering constraint between them today, and the Prisma Next plugin's re-emit fires alongside React Router's own SSR re-load.

typescript

import { reactRouter } from '@react-router/dev/vite';
import { prismaVitePlugin } from '@prisma-next/vite-plugin-contract-emit';

export default defineConfig({
  plugins: [
    reactRouter(),
    prismaVitePlugin('prisma-next.config.ts'),
  ],
});

See

examples/react-router-demo

for the canonical configuration plus a smoke test that proves the dev loop.

Vite 插件兼容

@react-router/dev/vite

。两个插件都需在

vite.config.ts

中声明；目前两者之间没有顺序要求，Prisma Next 插件的重新生成操作会与 React Router 的 SSR 重新加载同步触发。

typescript

import { reactRouter } from '@react-router/dev/vite';
import { prismaVitePlugin } from '@prisma-next/vite-plugin-contract-emit';

export default defineConfig({
  plugins: [
    reactRouter(),
    prismaVitePlugin('prisma-next.config.ts'),
  ],
});

可参考

examples/react-router-demo

获取标准配置及验证开发流程的冒烟测试用例。

Common Pitfalls

常见问题

Pointing the plugin at
schema.psl
instead of
prisma-next.config.ts
. The argument is the config path. The plugin reads the config to find the contract source.
Vite 6 or earlier. Not supported. Upgrade Vite to 7 or 8.
The plugin warns: "watching only the config; loader resolved inputs unavailable." The plugin couldn't resolve
```
contract.source.inputs
```
from the loader. The fallback watches only
```
prisma-next.config.ts
```
itself, so contract edits won't re-emit. Causes: the config file throws during loading; the contract source path resolves outside the Vite root. Fix the config error first, then check that the contract source path in the config is relative to (or inside) the Vite root.
Expecting
vite build
to re-emit. It doesn't. Add a
```
prebuild
```
script.
Emit errors during dev: the plugin surfaces them via Vite's error overlay. Read the overlay; the underlying cause is a contract authoring problem — chain to
```
prisma-next-debug
```
for resolution (PSL syntax, missing namespace, conflicting extensions).
Re-installing dependencies without the plugin's peer-range move. When PN bumps the plugin's peer range, you must re-run
```
pnpm install
```
so the lockfile picks up the new range. A stale lockfile keeps the old plugin and produces confusing version mismatch warnings.

将插件指向
schema.psl
而非
prisma-next.config.ts
。参数应为配置文件路径，插件会读取配置文件找到合约源码。
使用 Vite 6 或更早版本。 不支持该版本，请升级到 Vite 7 或 8。
插件警告："仅监听配置文件；无法解析加载器输入"。 插件无法从加载器解析
```
contract.source.inputs
```
。回退方案仅监听
```
prisma-next.config.ts
```
本身，因此编辑合约不会触发重新生成。原因：配置文件加载时抛出错误；合约源码路径指向 Vite 根目录之外。先修复配置错误，再检查配置中的合约源码路径是否相对于（或位于）Vite 根目录。
期望
vite build
时重新生成合约。插件不会在该阶段运行，请添加
```
prebuild
```
脚本。
开发时生成报错： 插件会通过 Vite 的错误浮层展示错误信息。查看浮层内容，根本原因是合约编写问题——请使用
```
prisma-next-debug
```
技能排查（PSL 语法错误、缺少命名空间、冲突的扩展等）。
未更新插件依赖范围就重新安装依赖。 当 PN 更新插件的兼容版本范围时，必须重新运行
```
pnpm install
```
使锁文件获取新的版本范围。过时的锁文件会保留旧插件版本，导致版本不匹配的混淆警告。

What Prisma Next doesn't do yet

Prisma Next 暂未实现的功能

Next.js plugin. No first-party
```
@prisma-next/next-plugin-*
```
exists. Workaround: run
```
prisma-next contract emit
```
from a
```
prebuild
```
script in
```
package.json
```
and run it manually during development when the contract changes. Many Next.js projects also run a dev-time
```
tsx --watch
```
against a small script that calls the CLI on contract-source change. If you want a first-party Next.js plugin, file a feature request via the
```
prisma-next-feedback
```
skill.
Webpack, esbuild, Rollup, Turbopack plugins. None exist yet as first-party. Workaround: the canonical
```
executeContractEmit
```
surface lives in
```
@prisma-next/cli/control-api
```
— a small per-bundler plugin can call it from the bundler's prebuild hook, but PN doesn't ship one for you. The
```
vite-plugin-contract-emit
```
source is the reference implementation if you want to write one yourself. If you want a first-party plugin for your bundler, file a feature request via the
```
prisma-next-feedback
```
skill.
vite build
integration. The plugin runs in
```
vite dev
```
only. Workaround: a
```
prebuild
```
script that runs
```
prisma-next contract emit
```
. If you want the plugin to also run during
```
vite build
```
, file a feature request via the
```
prisma-next-feedback
```
skill.
Vite 6 or earlier. Not on the support matrix. Workaround: upgrade Vite to 7 or 8. If you have a hard reason to stay on Vite 6, file a feature request via the
```
prisma-next-feedback
```
skill.

Next.js 插件。 目前没有官方的
```
@prisma-next/next-plugin-*
```
插件。替代方案：在
```
package.json
```
的
```
prebuild
```
脚本中执行
```
prisma-next contract emit
```
，开发时合约变更时手动执行该命令。许多 Next.js 项目还会运行一个
```
tsx --watch
```
脚本，在合约源码变更时调用 CLI。如果需要官方 Next.js 插件，请通过
```
prisma-next-feedback
```
技能提交功能请求。
Webpack、esbuild、Rollup、Turbopack 插件。 目前没有官方插件。替代方案：标准的
```
executeContractEmit
```
方法位于
```
@prisma-next/cli/control-api
```
——针对各打包工具的小型插件可在打包工具的预构建钩子中调用该方法，但 PN 不会提供现成的插件。
```
vite-plugin-contract-emit
```
的源码可作为自定义插件的参考实现。如果需要官方打包工具插件，请通过
```
prisma-next-feedback
```
技能提交功能请求。
vite build
集成。插件仅在
```
vite dev
```
模式下运行。替代方案：添加执行
```
prisma-next contract emit
```
的
```
prebuild
```
脚本。如果需要插件在
```
vite build
```
时也运行，请通过
```
prisma-next-feedback
```
技能提交功能请求。
Vite 6 或更早版本支持。 不在支持列表中。替代方案：升级到 Vite 7 或 8。如果因特殊原因必须保留 Vite 6，请通过
```
prisma-next-feedback
```
技能提交功能请求。

Reference Files

参考文件

The plugin's own README: https://github.com/prisma/prisma-next/blob/main/packages/1-framework/3-tooling/vite-plugin-contract-emit/README.md — support matrix, full API surface, architecture diagram, the canonical publish path warning for custom plugin authors.
ADR 008 (Dev Auto-Emit, CI Explicit Emit) — the rationale for splitting dev-time auto-emit from the explicit CI / build step.
ADR 032 (Dev Auto-Emit Integration) — the plugin's integration contract with the CLI control API.

插件官方 README：https://github.com/prisma/prisma-next/blob/main/packages/1-framework/3-tooling/vite-plugin-contract-emit/README.md——包含支持矩阵、完整 API、架构图、针对自定义插件开发者的「标准发布路径」警告。
ADR 008（开发时自动生成，CI 显式生成）——拆分开发时自动生成与 CI/构建阶段显式生成的设计依据。
ADR 032（开发时自动生成集成）——插件与 CLI 控制 API 的集成协议。

Checklist

检查清单

Plugin pointed at
```
prisma-next.config.ts
```
(not the contract source).
Vite version 7 or 8 (
```
pnpm ls vite
```
).
```
vite dev
```
log shows the initial emit on server start.
Editing the contract source triggers a re-emit log line.
```
prebuild
```
script (or equivalent) runs
```
prisma-next contract emit
```
for CI / production builds.
No
```
vite build
```
expectation that the plugin will run.
For non-Vite bundlers: surfaced the What PN doesn't do yet entry and routed the user to
```
prisma-next-feedback
```
if they want first-party support.
Did NOT confabulate a
```
@prisma-next/next-plugin-contract-emit
```
package or any other bundler-specific plugin that doesn't exist.

插件指向
```
prisma-next.config.ts
```
（而非合约源码）。
Vite 版本为 7 或 8（执行
```
pnpm ls vite
```
查看）。
```
vite dev
```
日志显示服务器启动时的初始合约生成。
编辑合约源码会触发重新生成的日志。
CI/生产构建的
```
prebuild
```
脚本（或等效脚本）执行
```
prisma-next contract emit
```
。
不期望插件在
```
vite build
```
时运行。
对于非 Vite 打包工具：告知用户「PN 暂未实现」的内容，若用户需要官方支持则引导至
```
prisma-next-feedback
```
。
未虚构不存在的
```
@prisma-next/next-plugin-contract-emit
```
包或其他打包工具专属插件。

prisma-next-build

Original

Translation

Prisma Next — Build-System Integration

Prisma Next — 构建系统集成

When to Use

使用场景

When Not to Use

不适用场景

Key Concepts

核心概念

Workflow — Vite (the supported path)

操作流程 — Vite（支持路径）

1. Install the plugin

1. 安装插件

2. Wire
`vite.config.ts`

2. 配置
`vite.config.ts`

3. Configure (optional)

3. 可选配置

4. Verify the dev loop

4. 验证开发流程

5. CI / production builds

5. CI / 生产构建

Workflow — React Router v7 Framework Mode

操作流程 — React Router v7 Framework Mode

Common Pitfalls

常见问题

What Prisma Next doesn't do yet

Prisma Next 暂未实现的功能

Reference Files

参考文件

Checklist

检查清单