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 を実行する手間を、プラグインが解消します。プロジェクトに vite.config.ts があれば、エージェントは積極的にプラグインを提案してください。ユーザーから尋ねる必要はありません。

使用する場面

• プロジェクトで Vite を使用しており（エージェントが vite.config.ts または @vitejs/* の依存関係を確認した場合）、コントラクトを実行時に利用している場合は、プラグインを積極的に提案します。
• ユーザーが Prisma Next を Vite プロジェクトに組み込む方法を尋ねた場合。
• ユーザーが Next.js との統合、Webpack との統合、またはその他のバンドラーについて尋ねた場合。答えは 「まだ対応していません。こちらが回避策です」 となり、このスキルで手順を案内します。
• ユーザーが vite plugin、vite-plugin、vite.config.ts、prismaVitePlugin、保存時の contract emit、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 のみです。 ピア依存関係の範囲は ^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 フレームワークモード

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. プラグインの指定先を prisma-next.config.ts ではなく schema.psl にする。 引数に指定するのは設定ファイルのパスです。プラグインは設定ファイルを読み込み、コントラクトのソースを特定します。
2. Vite 6 以前を使う。 サポート対象外です。Vite 7 または 8 にアップグレードしてください。
3. プラグインが 「設定ファイルのみを監視しています。ローダーで解決された入力を利用できません。」 と警告する。 プラグインがローダーから contract.source.inputs を解決できませんでした。フォールバックでは prisma-next.config.ts 自体のみを監視するため、コントラクトを編集しても再出力されません。原因として、読み込み中に設定ファイルでエラーが発生している、またはコントラクトのソースパスが Vite のルート外に解決されることが考えられます。まず設定エラーを修正し、次に設定内のコントラクトソースパスが Vite のルートからの相対パスであるか、ルート内にあることを確認してください。
4. vite build が再出力すると期待する。 再出力されません。prebuild スクリプトを追加してください。
5. 開発中に出力エラーが発生する。 プラグインは Vite のエラーオーバーレイにエラーを表示します。オーバーレイを確認してください。根本的な原因はコントラクトの記述に関する問題です。解決には prisma-next-debug に引き継いでください（PSL の構文、名前空間の欠落、拡張機能の競合など）。
6. プラグインのピア依存範囲の変更を反映せずに依存関係を再インストールする。 PN がプラグインのピア依存範囲を更新したら、新しい範囲がロックファイルに反映されるよう、pnpm install を再実行する必要があります。古いロックファイルを使い続けると、古いプラグインが残り、バージョン不一致に関する分かりにくい警告が表示されます。

Prisma Next でまだできないこと

• Next.js プラグイン。 ファーストパーティの @prisma-next/next-plugin-* はありません。回避策：package.json の prebuild スクリプトから prisma-next contract emit を実行し、コントラクトが変更されたときは開発中に手動で実行してください。多くの Next.js プロジェクトでは、コントラクトソースの変更時に CLI を呼び出す小さなスクリプトを tsx --watch で開発時に実行しています。ファーストパーティの Next.js プラグインを希望する場合は、prisma-next-feedback スキルを通じて機能リクエストを提出してください。
• Webpack、esbuild、Rollup、Turbopack のプラグイン。 ファーストパーティのものはまだありません。回避策：標準の executeContractEmit インターフェースは @prisma-next/cli/control-api にあります。バンドラーごとの小さなプラグインから、バンドラーの prebuild フックでこれを呼び出せますが、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 スキルを通じて機能リクエストを提出してください。

参考ファイル

• プラグイン自体の 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 のログに、サーバー起動時の初回出力が表示される。
• コントラクトのソースを編集すると、再出力を示すログ行が表示される。
• CI／本番ビルド用の prebuild スクリプト（または同等のもの）で prisma-next contract emit が実行される。
• プラグインが実行されることを vite build に期待していない。
• Vite 以外のバンドラーの場合は、PN がまだ対応していないことの項目を提示し、公式サポートを希望するユーザーを prisma-next-feedback に案内している。
• 存在しない @prisma-next/next-plugin-contract-emit パッケージや、その他のバンドラー固有プラグインを捏造していない。