inngest-setup

Inngest のセットアップ

このスキルは、TypeScript プロジェクトで Inngest をゼロからセットアップするためのもので、インストール、クライアント設定、接続モード、ローカル開発を網羅します。

これらのスキルは TypeScript に焦点を当てています。 Python または Go については、言語固有のガイダンスとして Inngest ドキュメント を参照してください。コアコンセプトはすべての言語に適用されます。

前提条件

• Node.js 18 以上（WebSocket サポートには Node.js 22.4 以上を推奨）
• TypeScript プロジェクト
• パッケージマネージャー（npm、yarn、pnpm、または bun）

ステップ 1: Inngest SDK をインストールする

プロジェクトに inngest npm パッケージをインストールします:

npm install inngest
# or
yarn add inngest
# or
pnpm add inngest
# or
bun add inngest

ステップ 2: Inngest クライアントを作成する

コードベース全体でインポートする共有クライアントファイルを作成します:

// src/inngest/client.ts
import { Inngest } from "inngest";

export const inngest = new Inngest({
  id: "my-app" // Unique identifier for your application (hyphenated slug)
});
// IMPORTANT: v4 defaults to Cloud mode. For local dev, set INNGEST_DEV=1 env var.
// Without it, your serve endpoint will return 500 ("In cloud mode but no signing key").
// In production, set INNGEST_SIGNING_KEY (required for Cloud mode).

主な設定オプション

• id（必須）: アプリの一意の識別子。"my-app" や "user-service" のようなハイフン区切りのスラッグを使用します
• eventKey: イベント送信用のイベントキー（INNGEST_EVENT_KEY 環境変数を推奨）
• env: Branch Environments 用の環境名
• isDev: Dev モード（true）または Cloud モード（false）を強制します。v4 では Cloud モードがデフォルトのため、ローカル開発では INNGEST_DEV=1 環境変数を設定してください。ソースコードに isDev: true をハードコードしないでください — 本番環境でサイレントに壊れます。常に環境変数を使用してください。
• signingKey: 本番用の署名キー（INNGEST_SIGNING_KEY 環境変数を推奨）。v4 で serve() からクライアントに移動しました
• signingKeyFallback: キーローテーション用のフォールバック署名キー（INNGEST_SIGNING_KEY_FALLBACK 環境変数を推奨）
• baseUrl: カスタム Inngest API ベース URL（INNGEST_BASE_URL 環境変数を推奨）
• logger: カスタムロガーインスタンス（例: winston、pino） — 関数コンテキストで logger を有効にします
• middleware: ミドルウェアの配列（inngest-middleware スキルを参照）

eventType() による型付きイベント

import { Inngest, eventType } from "inngest";
import { z } from "zod";

const signupCompleted = eventType("user/signup.completed", {
  schema: z.object({
    userId: z.string(),
    email: z.string(),
    plan: z.enum(["free", "pro"])
  })
});

const orderPlaced = eventType("order/placed", {
  schema: z.object({
    orderId: z.string(),
    amount: z.number()
  })
});

export const inngest = new Inngest({ id: "my-app" });

// Use event types as triggers for full type safety:
inngest.createFunction(
  { id: "handle-signup", triggers: [signupCompleted] },
  async ({ event }) => {
    event.data.userId; /* typed as string */
  }
);

// Use event types when sending events:
await inngest.send(
  signupCompleted.create({
    userId: "user_123",
    email: "[email protected]",
    plan: "pro"
  })
);

環境変数のセットアップ

これらの環境変数を .env ファイルまたはデプロイ環境で設定します:

# Required for production
INNGEST_EVENT_KEY=your-event-key-here
INNGEST_SIGNING_KEY=your-signing-key-here

# Force dev mode during local development
INNGEST_DEV=1

# Optional - custom dev server URL (default: http://localhost:8288)
INNGEST_BASE_URL=http://localhost:8288

⚠️ よくある落とし穴: ソースコードにキーをハードコードしないでください。INNGEST_EVENT_KEY と INNGEST_SIGNING_KEY には常に環境変数を使用してください。

重要: ローカル開発では Dev モードを有効にする

serve エンドポイントを作成したり worker を接続する前に、dev モードが有効になっていることを確認してください。 これがないと、Inngest は Cloud モードをデフォルトとし、エンドポイントは 500 エラーで失敗します。

.env ファイル（または package.json の dev スクリプト）に追加します:

INNGEST_DEV=1

または package.json の scripts で:

{
  "scripts": {
    "dev": "INNGEST_DEV=1 tsx --watch src/server.ts"
  }
}

INNGEST_DEV が欠落している場合の症状:

• GET /api/inngest が {"code":"internal_server_error"} を返す
• サーバーログ: "In cloud mode but no signing key found"
• dev サーバーがアプリと同期できない

ステップ 3: 接続モードを選択する

Inngest は 2 つの接続モードをサポートしています:

モード A: Serve エンドポイント（HTTP）

サーバーレスプラットフォーム（Vercel、Lambda など）や既存の API に最適です。

モード B: Connect（WebSocket）

コンテナランタイム（Kubernetes、Docker）や長時間実行プロセスに最適です。

ステップ 4A: エンドポイントを serve する（HTTP モード）

関数を Inngest に公開する API エンドポイントを作成します:

// For Next.js App Router: src/app/api/inngest/route.ts
import { serve } from "inngest/next";
import { inngest } from "../../../inngest/client";
import { myFunction } from "../../../inngest/functions";

export const { GET, POST, PUT } = serve({
  client: inngest,
  functions: [myFunction]
});

// For Next.js Pages Router: pages/api/inngest.ts
import { serve } from "inngest/next";
import { inngest } from "../../inngest/client";
import { myFunction } from "../../inngest/functions";

export default serve({
  client: inngest,
  functions: [myFunction]
});

// For Express.js
import express from "express";
import { serve } from "inngest/express";
import { inngest } from "./inngest/client";
import { myFunction } from "./inngest/functions";

const app = express();
app.use(express.json({ limit: "10mb" })); // Required for Inngest, increase limit for larger function state

app.use(
  "/api/inngest",
  serve({
    client: inngest,
    functions: [myFunction]
  })
);

🔧 フレームワーク固有の注意点:

• Express: より大きな関数状態をサポートするには express.json({ limit: "10mb" }) ミドルウェアを使用する必要があります。
• Fastify: inngest/fastify の fastifyPlugin を使用します
• Cloudflare Workers: inngest/cloudflare を使用します
• AWS Lambda: inngest/lambda を使用します
• その他すべてのフレームワークについては、serve のリファレンスをこちらで確認してください: https://www.inngest.com/docs-markdown/learn/serving-inngest-functions

⚠️ v4 の変更: signingKey、signingKeyFallback、baseUrl などのオプションは、serve() ではなく Inngest クライアントのコンストラクターで設定するようになりました。serve() 関数は client、functions、streaming のみを受け付けます。

⚠️ よくある落とし穴: エンドポイントパスには常に /api/inngest を使用してください。これにより自動検出が有効になります。別のパスを使用する必要がある場合は、-u フラグで検出を手動設定する必要があります。

ステップ 4B: Worker として接続する（WebSocket モード）

永続的な接続を維持する長時間実行アプリケーション向け:

// src/worker.ts
import { connect } from "inngest/connect";
import { inngest } from "./inngest/client";
import { myFunction } from "./inngest/functions";

(async () => {
  const connection = await connect({
    apps: [{ client: inngest, functions: [myFunction] }],
    instanceId: process.env.HOSTNAME, // Unique worker identifier
    maxWorkerConcurrency: 10 // Max concurrent steps
  });

  console.log("Worker connected:", connection.state);

  // Graceful shutdown handling
  await connection.closed;
  console.log("Worker shut down");
})();

接続モードの要件:

• WebSocket サポートには Node.js 22.4+（または Deno 1.4+、Bun 1.1+）が必要
• 長時間実行サーバー環境（サーバーレスではない）
• 本番環境には INNGEST_SIGNING_KEY と INNGEST_EVENT_KEY
• ローリングデプロイをサポートするには、本番環境で Inngest クライアントの appVersion パラメータを設定

v4 接続の変更点:

• ワーカースレッド分離 がデフォルトで有効になりました — WebSocket 接続はイベントループの枯渇を防ぐためにワーカースレッドで実行されます。単一プロセスを使用するには isolateExecution: false を設定してください（または INNGEST_CONNECT_ISOLATE_EXECUTION=false）
• rewriteGatewayEndpoint コールバックは gatewayUrl 文字列オプション（または INNGEST_CONNECT_GATEWAY_URL 環境変数）に置き換えられました

ステップ 5: アプリで整理する

システムが成長するにつれて、関数を論理的なアプリに整理します:

// User service
const userService = new Inngest({ id: "user-service" });

// Payment service
const paymentService = new Inngest({ id: "payment-service" });

// Email service
const emailService = new Inngest({ id: "email-service" });

各アプリは Inngest ダッシュボードで独自のセクションを持ち、独立してデプロイできます。サービスのアーキテクチャに一致する、説明的でハイフン区切りの ID を使用してください。

⚠️ よくある落とし穴: アプリの id を変更すると、Inngest に新しいアプリが作成されます。デプロイ間で ID を一貫させてください。

ステップ 6: inngest-cli によるローカル開発

ローカル開発用に Inngest Dev Server を起動します:

# Auto-discover your app on common ports/endpoints
npx --ignore-scripts=false inngest-cli@latest dev

# Specify your app's URL manually
npx --ignore-scripts=false inngest-cli@latest dev -u http://localhost:3000/api/inngest

# Custom port for dev server
npx --ignore-scripts=false inngest-cli@latest dev -p 9999

# Disable auto-discovery
npx --ignore-scripts=false inngest-cli@latest dev --no-discovery -u http://localhost:3000/api/inngest

# Multiple apps
npx --ignore-scripts=false inngest-cli@latest dev -u http://localhost:3000/api/inngest -u http://localhost:4000/api/inngest

Dev Server はデフォルトで http://localhost:8288 で利用可能になります。

設定ファイル（任意）

複雑なセットアップ用に inngest.json を作成します:

{
  "sdk-url": [
    "http://localhost:3000/api/inngest",
    "http://localhost:4000/api/inngest"
  ],
  "port": 8289,
  "no-discovery": true
}

環境別のセットアップ

ローカル開発

INNGEST_DEV=1
# No keys required in dev mode

本番環境

INNGEST_EVENT_KEY=evt_your_production_event_key
INNGEST_SIGNING_KEY=signkey_your_production_signing_key

Dev Server のカスタムポート

INNGEST_DEV=1
INNGEST_BASE_URL=http://localhost:9999

アプリが標準以外のポート（3000 以外）で実行されている場合は、-u フラグで URL を指定して、Dev Server がアプリに到達できるようにしてください。

よくある問題と解決策

ポートの競合: ポート 8288 が使用中の場合は、別のポートを指定します: -p 9999

自動検出が機能しない: 手動で URL を指定します: -u http://localhost:YOUR_PORT/api/inngest。--no-discovery フラグを使用している場合、-u フラグは 必須 です — これがないと Dev Server はアプリを見つけられません。

関数が Dev Server に表示されない: アプリは Dev Server に登録する必要があります。これは、serve エンドポイントが Dev Server から最初のリクエストを受信したときに自動的に行われます。登録が行われない場合は、(1) INNGEST_DEV=1 が設定されていることを確認し、(2) Dev Server がアプリの URL に到達できることを確認し、(3) Dev Server の実行中にアプリを再起動してみてください。

署名検証エラー: 本番環境で INNGEST_SIGNING_KEY が正しく設定されていることを確認してください

WebSocket 接続の問題: 接続モードには Node.js バージョン 22.4+ を確認してください

Docker 開発: Docker で Dev Server を実行する場合、アプリの URL には host.docker.internal を使用してください

次のステップ

1. inngest.createFunction() で最初の Inngest 関数を作成する
2. Dev Server の「Invoke」ボタンを使用して関数をテストする
3. inngest.send() でイベントを送信して関数をトリガーする
4. 適切な環境変数を使用して本番環境にデプロイする
5. ロギング、エラートラッキング、その他の横断的関心事の追加については inngest-middleware を参照してください
6. Inngest ダッシュボードで関数を監視する

Dev Server は関数を変更すると自動的にリロードされるため、開発が迅速かつ反復的になります。