prisma-next-build

Prisma Next — 构建系统集成

编辑数据契约。其余交给 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 很不方便，而插件正好可以省去这一步。只要 Agent 在项目中发现 vite.config.ts，就应主动推荐此插件；用户无需开口询问。

适用场景

• 项目使用 Vite（Agent 发现了 vite.config.ts 或 @vitejs/* 依赖），且运行时会消费契约——主动推荐此插件。
• 用户询问如何将 Prisma Next 接入其 Vite 项目。
• 用户询问 Next.js 集成、Webpack 集成或其他打包工具——回答应为 “目前还不支持，这是变通方案”，并引导用户按本技能操作。
• 用户提到：vite plugin、vite-plugin、vite.config.ts、prismaVitePlugin、保存时生成契约、HMR、热重载契约、开发服务器、vite 7、vite 8。
• 用户在 Prisma Next 集成的语境下提到 Next.js／Webpack／esbuild／Rollup／Turbopack——应进入列出支持缺口的处理流程。

不适用场景

• 用户想接入 db.ts 和中间件 → prisma-next-runtime。
• 用户想为尚未实现的打包工具插件提交功能请求 → prisma-next-feedback。

核心概念

• 插件的职责是在打包工具安排的时机运行 contract emit。 这不是运行时关注点——运行时，应用读取 contract.json／contract.d.ts 的方式并不会因它们由插件还是脚本生成而不同。插件省去了开发期间手动运行命令的步骤。
• 仅支持 Vite 7 和 Vite 8。 Peer 范围为 ^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。

工作流 — Vite（受支持的路径）

1. 安装插件

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

（也可以使用 npm install --save-dev、yarn add -D、bun add -d——根据项目使用的包管理器选择。）

2. 配置 vite.config.ts

// 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. 配置（可选）

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

仅在排查问题时设置 logLevel: 'debug'；已提交的配置应使用默认值 'info'，避免开发服务器输出过多日志。

4. 验证开发循环

1. 启动 vite dev。
2. 等待成功日志：[prisma-next] emitted contract.d.ts + contract.json。
3. 编辑 prisma/schema.psl（例如，向模型添加字段）。
4. 大约 150ms（防抖时间）后，观察是否出现重新生成的日志行。
5. 对使用新字段的应用代码进行类型检查——无需重启开发服务器即可通过。

如果插件提示正在进行仅监视配置文件，请参阅常见问题。

5. CI／生产构建

插件不会在 vite build 期间运行。对于 CI 和生产部署，请将 prisma-next contract emit 作为预构建步骤运行：

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

pnpm build 随后会在 build 之前自动运行 prebuild。

工作流 — React Router v7 Framework Mode

Vite 插件兼容 @react-router/dev/vite。两个插件都列在 vite.config.ts 中；目前它们之间没有顺序限制，Prisma Next 插件的重新发射会与 React Router 自身的 SSR 重新加载同时触发。

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，了解标准配置以及用于验证开发循环的冒烟测试。

常见问题

1. 将插件指向 schema.psl，而不是 prisma-next.config.ts。 参数应为配置文件路径。插件会读取配置以查找契约源。
2. 使用 Vite 6 或更早版本。 不受支持。请将 Vite 升级到 7 或 8。
3. 插件发出警告："watching only the config; loader resolved inputs unavailable." 插件无法从加载器解析 contract.source.inputs。回退机制只会监视 prisma-next.config.ts 本身，因此契约编辑不会触发重新发射。可能原因：加载配置文件时发生错误；契约源路径解析到了 Vite 根目录之外。请先修复配置错误，然后检查配置中的契约源路径是否相对于 Vite 根目录（或位于其中）。
4. 期待 vite build 重新发射。 它不会。请添加 prebuild 脚本。
5. 开发期间发生发射错误：插件会通过 Vite 的错误浮层显示错误。请查看错误浮层；根本原因是契约编写问题——可使用 prisma-next-debug 进行排查（PSL 语法、缺少命名空间、扩展冲突）。
6. 在未更新插件 peer 范围的情况下重新安装依赖。 当 PN 更新插件的 peer 范围时，必须重新运行 pnpm install，让 lockfile 获取新的范围。过时的 lockfile 会保留旧插件，并产生令人困惑的版本不匹配警告。

Prisma Next 目前尚不支持的功能

• 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 中——可以编写一个简单的 bundler 专用插件，在 bundler 的预构建钩子中调用它，但 PN 不会为你提供现成插件。如果你想自行编写插件，可以将 vite-plugin-contract-emit 源码作为参考实现。如果你希望为所用 bundler 推出官方插件，请通过 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 技能提交功能请求。

参考文件

• 插件自己的 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 之间的集成约定。

检查清单

• 插件指向 prisma-next.config.ts（而非契约源文件）。
• Vite 版本为 7 或 8（pnpm ls vite）。
• vite dev 日志显示服务器启动时的初始生成记录。
• 编辑契约源文件会触发一条重新生成日志。
• prebuild 脚本（或等效脚本）会为 CI / 生产构建运行 prisma-next contract emit。
• 不要预期插件会在 vite build 时运行。
• 对于非 Vite 打包工具：已指出 What PN doesn't do yet 条目；如果用户希望获得官方支持，则引导其前往 prisma-next-feedback。
• 未捏造 @prisma-next/next-plugin-contract-emit 包或任何其他不存在的、特定于打包工具的插件。