inngest-nextjs-patterns

Inngest + Next.js のパターン

Next.js App Router プロジェクトから Inngest 上でイベント駆動型の永続的なバックグラウンド処理を構築するためのテンプレートと規約です。このスキルでは、Inngest の公式ドキュメントで使われている規約（分散型の eventType() スキーマ、ケバブケースの安定した関数 ID、冪等なステップ）を適用し、リトライ、リプレイ、同時実行制御が意図どおりに動作するようにします。

適用するタイミング

次の作業を行う場合は、このスキルを参照してください。

• Next.js アプリで初めて Inngest を設定するとき（クライアント + ルートハンドラー + 最初の関数）
• Next.js アプリに新しいバックグラウンドジョブ、Webhook ハンドラー、またはスケジュール済みタスクを追加するとき
• 他の関数がトリガーする新しいドメインイベントを定義するとき
• プロセスの再起動後も維持する必要がある複数ステップの処理（永続的なワークフロー、サガ）をオーケストレーションするとき
• イベント名、ステップの冪等性、または安定した関数 ID に関する既存の Inngest コードをレビューするとき
• setTimeout / キューライブラリ / cron サービスから Inngest の永続的な実行モデルに移行するとき

使用方法

1. このコードベースを初めて使いますか？ 何かを書く前に、references/conventions.md を読んでください。規約では、イベント名が特定の形式になる理由、関数 ID を安定させる必要がある理由、すべての step.run に冪等性が必要な理由を説明しています。その理由を理解すると、テンプレートの意図がわかります。
2. 作成するものに応じて、以下の一覧からテンプレートを選びます。
3. 文書化されたパラメーターを置き換えてテンプレートを展開します。各テンプレートファイルの先頭にパラメーターの表があります。
4. 接続します： 新しい関数は src/inngest/functions/index.ts（ルートハンドラーが読み込むレジストリ）に追加する必要があります。レジストリのパターンについては、規約ドキュメントを参照してください。

利用可能なテンプレート

テンプレート	出力パス	使用するタイミング
client.ts.template	src/inngest/client.ts	初回設定：シングルトンの Inngest クライアントを作成します。アプリごとに 1 回生成します。
route-handler.ts.template	src/app/api/inngest/route.ts	初回設定：Inngest が関数を呼び出すためにアクセスする App Router エンドポイントです。アプリごとに 1 回生成します。
event.ts.template	src/inngest/events/{domain}.ts	プロデューサーが送信し、関数が受け取る、新しい型付きイベント（Zod スキーマ付き）を定義します。
function.ts.template	src/inngest/functions/{name}.ts	ステップを含む、標準的なイベントトリガー型の永続的な関数です。リトライ、同時実行数、スロットル、デバウンス、cancelOn、onFailure をパラメーターで設定できます。
function-cron.ts.template	src/inngest/functions/{name}.ts	スケジュール済み関数です。タイムゾーン付きの cron 式で実行します。任意で手動イベントトリガーも受け付け、必要に応じて呼び出せます。
function-fan-out.ts.template	src/inngest/functions/{name}.ts	1 つのイベントを受け取り、step.sendEvent（実行結果を待たない）または Promise.all(step.invoke(...))（結果を待つ）で作業を分散するオーケストレーターです。

クイックリファレンス

• イベント名の形式： domain/entity.verb_past — 例：app/user.created、shop/order.placed、billing/invoice.paid。詳細なルールは規約ドキュメントを参照してください。
• 関数の id： 安定したケバブケースにします。デプロイ後は絶対に変更しないでください。Inngest はこれを永続状態のキーとして使用します。
• ステップの id： 説明的なケバブケースにします。こちらも永続的です。変更すると、リプレイ時にそのステップが再実行されます。
• 冪等性： すべての step.run は安全にリトライできる必要があります。状態を変更するサードパーティ API を呼び出す場合は、冪等性キーを渡してください。
• 開発サーバー： npx inngest-cli@latest dev を実行すると、http://localhost:8288 で UI を利用できます。SDK の接続先にするには、.env.local に INNGEST_DEV=1 を設定してください。

プロジェクトのディレクトリ構成に関する前提

テンプレートでは、App Router を使用する src/ ディレクトリがあることを前提としています。

src/
├── app/api/inngest/route.ts          # generated by route-handler template
└── inngest/
    ├── client.ts                     # generated by client template
    ├── events/                       # one file per domain (events.shop.ts, events.user.ts)
    │   └── {domain}.ts               # generated by event template
    └── functions/
        ├── index.ts                  # registry: re-exports all functions as an array
        └── {name}.ts                 # generated by function/cron/fan-out templates

プロジェクトの構成が異なる場合（src/ がない、または Pages Router を使用している場合）は、config.json で出力パスを上書きしてください。規約に関するドキュメントで、選択肢ごとのトレードオフを説明しています。

セットアップ

config.json でパスの上書きを設定します。初回使用時は、各フィールドが入力されているか確認してください。入力されていない場合は、生成する前にユーザーに確認してください（プロジェクトのルートがデフォルトの前提と異なるためです）。

関連するスキル

• vercel:ai-sdk — Inngest の関数から LLM を呼び出す場合、AI SDK を使うとストリーミングとプロバイダーの抽象化を利用できます。再試行時の安全性を確保するため、step.run と組み合わせてください。
• vercel:vercel-functions — Next.js 用の Inngest の serve() アダプターは、デフォルトで Vercel Serverless Function として実行されます。AI SDK のスキルには、長時間実行されるエージェント向けの Fluid Compute とタイムアウト延長に関する補足があります。