TypeScript项目Inngest设置指南：从零开始配置事件驱动工作流

inngest-setup by inngest/inngest-skills

273 周安装量

15 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/inngest/inngest-skills --skill inngest-setup

开发自动化 TypeScript

🇨🇳中文介绍

Inngest 设置

此技能指导如何在 TypeScript 项目中从零开始设置 Inngest，涵盖安装、客户端配置、连接模式以及本地开发。

这些技能主要针对 TypeScript。 对于 Python 或 Go，请参考 Inngest 文档获取特定语言的指导。核心概念在所有语言中都是通用的。

先决条件

Node.js 18+（推荐 Node.js 22.4+ 以获得 WebSocket 支持）
TypeScript 项目
包管理器（npm、yarn、pnpm 或 bun）

步骤 1：安装 Inngest SDK

在您的项目中安装 inngest npm 包：

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

步骤 2：创建 Inngest 客户端

创建一个共享的客户端文件，以便在整个代码库中导入：

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

export const inngest = new Inngest({
  id: "my-app" // 应用程序的唯一标识符（使用连字符分隔的短名称）
});
// 在开发环境中，必须设置环境变量 INNGEST_DEV=1 或使用 isDev: true
// 在生产环境中，需要 INNGEST_SIGNING_KEY（v4 版本默认使用 Cloud 模式）

关键配置选项

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

使用 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" });

// 将事件类型用作触发器以实现完整的类型安全：
inngest.createFunction(
  { id: "handle-signup", triggers: [signupCompleted] },
  async ({ event }) => {
    event.data.userId; /* 类型化为 string */
  }
);

// 发送事件时使用事件类型：
await inngest.send(
  signupCompleted.create({
    userId: "user_123",
    email: "user@example.com",
    plan: "pro"
  })
);

在您的 .env 文件或部署环境中设置以下环境变量：

# 生产环境必需
INNGEST_EVENT_KEY=your-event-key-here
INNGEST_SIGNING_KEY=your-signing-key-here

# 在本地开发期间强制启用开发模式
INNGEST_DEV=1

# 可选 - 自定义开发服务器 URL（默认：http://localhost:8288）
INNGEST_BASE_URL=http://localhost:8288

⚠️ 常见陷阱：切勿在源代码中硬编码密钥。始终使用环境变量来设置 INNGEST_EVENT_KEY 和 INNGEST_SIGNING_KEY。

步骤 3：选择连接模式

Inngest 支持两种连接模式：

模式 A：服务端点（HTTP）

最适合无服务器平台（Vercel、Lambda 等）和现有 API。

模式 B：连接（WebSocket）

最适合容器运行时（Kubernetes、Docker）和长时间运行的进程。

步骤 4A：提供服务端点（HTTP 模式）

创建一个 API 端点，将您的函数暴露给 Inngest：

// 对于 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]
});

// 对于 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]
});

// 对于 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" })); // Inngest 必需，为更大的函数状态增加限制

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 等选项现在在 Inngest 客户端构造函数上配置，而不是在 serve() 上。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, // 唯一的 worker 标识符
    maxWorkerConcurrency: 10 // 最大并发步骤数
  });

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

  // 优雅关闭处理
  await connection.closed;
  console.log("Worker shut down");
})();

连接模式要求：

Node.js 22.4+（或 Deno 1.4+、Bun 1.1+）以获得 WebSocket 支持
长时运行的服务器环境（非无服务器）
生产环境需要 INNGEST_SIGNING_KEY 和 INNGEST_EVENT_KEY
在生产环境中，在 Inngest 客户端上设置 appVersion 参数以支持滚动部署

v4 连接变更：

Worker 线程隔离 默认启用 —— WebSocket 连接在 worker 线程中执行，以防止事件循环阻塞。设置 isolateExecution: false 以使用单进程（或设置 INNGEST_CONNECT_ISOLATE_EXECUTION=false）
rewriteGatewayEndpoint 回调已被 gatewayUrl 字符串选项（或 INNGEST_CONNECT_GATEWAY_URL 环境变量）取代

步骤 5：使用 Apps 进行组织

随着系统增长，将函数组织到逻辑应用程序中：

// 用户服务
const userService = new Inngest({ id: "user-service" });

// 支付服务
const paymentService = new Inngest({ id: "payment-service" });

// 邮件服务
const emailService = new Inngest({ id: "email-service" });

每个应用程序在 Inngest 仪表板中都有自己的部分，并且可以独立部署。使用描述性的、连字符分隔的 ID，使其与您的服务架构相匹配。

⚠️ 常见陷阱：更改应用程序的 id 会在 Inngest 中创建一个新的应用程序。请确保在部署过程中保持 ID 一致。

步骤 6：使用 inngest-cli 进行本地开发

启动 Inngest 开发服务器进行本地开发：

# 在常见端口/端点上自动发现您的应用
npx --ignore-scripts=false inngest-cli@latest dev

# 手动指定应用的 URL
npx --ignore-scripts=false inngest-cli@latest dev -u http://localhost:3000/api/inngest

# 为开发服务器指定自定义端口
npx --ignore-scripts=false inngest-cli@latest dev -p 9999

# 禁用自动发现
npx --ignore-scripts=false inngest-cli@latest dev --no-discovery -u http://localhost:3000/api/inngest

# 多个应用
npx --ignore-scripts=false inngest-cli@latest dev -u http://localhost:3000/api/inngest -u http://localhost:4000/api/inngest

默认情况下，开发服务器将在 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
# 开发模式下不需要密钥

INNGEST_EVENT_KEY=evt_your_production_event_key
INNGEST_SIGNING_KEY=signkey_your_production_signing_key

自定义开发服务器端口

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

如果您的应用程序运行在非标准端口（非 3000），请确保开发服务器可以通过指定带有 -u 标志的 URL 来访问它。

常见问题与解决方案

端口冲突：如果端口 8288 被占用，请指定其他端口：-p 9999

自动发现不工作：使用手动 URL 指定：-u http://localhost:YOUR_PORT/api/inngest

签名验证错误：确保在生产环境中正确设置了 INNGEST_SIGNING_KEY

WebSocket 连接问题：验证 Node.js 版本是否为 22.4+（连接模式）

Docker 开发：在 Docker 中运行开发服务器时，对应用 URL 使用 host.docker.internal

使用 inngest.createFunction() 创建您的第一个 Inngest 函数
使用开发服务器的“Invoke”按钮测试函数
使用 inngest.send() 发送事件以触发函数
使用正确的环境变量部署到生产环境
参见 inngest-middleware 以添加日志记录、错误跟踪和其他横切关注点
在 Inngest 仪表板中监控函数

开发服务器会在您更改函数时自动重新加载，使开发快速且迭代。

🇺🇸English

Inngest Setup

This skill sets up Inngest in a TypeScript project from scratch, covering installation, client configuration, connection modes, and local development.

These skills are focused on TypeScript. For Python or Go, refer to the Inngest documentation for language-specific guidance. Core concepts apply across all languages.

Prerequisites

Node.js 18+ (Node.js 22.4+ r ecommended for WebSocket support)
TypeScript project
Package manager (npm, yarn, pnpm, or bun)

Step 1: Install the Inngest SDK

Install the inngest npm package in your project:

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

Step 2: Create an Inngest Client

Create a shared client file that you'll import throughout your codebase:

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

export const inngest = new Inngest({
  id: "my-app" // Unique identifier for your application (hyphenated slug)
});
// In development, you must set the INNGEST_DEV=1 env var or use isDev: true
// In production, INNGEST_SIGNING_KEY is required (v4 defaults to Cloud mode)

Key Configuration Options

id (required): Unique identifier for your app. Use a hyphenated slug like "my-app" or "user-service"
eventKey : Event key for sending events (prefer INNGEST_EVENT_KEY env var)
env : Environment name for Branch Environments
isDev : Force Dev mode (true) or Cloud mode (false). v4 defaults to Cloud mode , so set isDev: true or for local development

Typed Events with 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: "user@example.com",
    plan: "pro"
  })
);

Environment Variables Setup

Set these environment variables in your .env file or deployment environment:

# 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

⚠️ Common Gotcha : Never hardcode keys in your source code. Always use environment variables for INNGEST_EVENT_KEY and INNGEST_SIGNING_KEY.

Step 3: Choose Your Connection Mode

Inngest supports two connection modes:

Mode A: Serve Endpoint (HTTP)

Best for serverless platforms (Vercel, Lambda, etc.) and existing APIs.

Mode B: Connect (WebSocket)

Best for container runtimes (Kubernetes, Docker) and long-running processes.

Step 4A: Serving an Endpoint (HTTP Mode)

Create an API endpoint that exposes your functions to Inngest:

// 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]
  })
);

🔧 Framework-Specific Notes :

Express : Must use express.json({ limit: "10mb" }) middleware to support larger function state.
Fastify : Use fastifyPlugin from inngest/fastify
Cloudflare Workers : Use inngest/cloudflare
AWS Lambda : Use inngest/lambda
For all other frameworks, check the serve reference here: https://www.inngest.com/docs-markdown/learn/serving-inngest-functions

⚠️ v4 Change: Options like signingKey, signingKeyFallback, and baseUrl are now configured on the Inngest client constructor, not on serve(). The serve() function only accepts client, functions, and streaming.

⚠️ Common Gotcha : Always use /api/inngest as your endpoint path. This enables automatic discovery. If you must use a different path, you'll need to configure discovery manually with the -u flag.

Step 4B: Connect as Worker (WebSocket Mode)

For long-running applications that maintain persistent connections:

// 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");
})();

Requirements for Connect Mode :

Node.js 22.4+ (or Deno 1.4+, Bun 1.1+) for WebSocket support
Long-running server environment (not serverless)
INNGEST_SIGNING_KEY and INNGEST_EVENT_KEY for production
Set the appVersion parameter on the Inngest client for production to support rolling deploys

v4 Connect Changes:

Worker thread isolation is enabled by default — WebSocket connections execute in a worker thread to prevent event loop starvation. Set isolateExecution: false to use a single process (or INNGEST_CONNECT_ISOLATE_EXECUTION=false)
rewriteGatewayEndpoint callback has been replaced with the gatewayUrl string option (or INNGEST_CONNECT_GATEWAY_URL env var)

Step 5: Organizing with Apps

As your system grows, organize functions into logical apps:

// 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" });

Each app gets its own section in the Inngest dashboard and can be deployed independently. Use descriptive, hyphenated IDs that match your service architecture.

⚠️ Common Gotcha : Changing an app's id creates a new app in Inngest. Keep IDs consistent across deployments.

Step 6: Local Development with inngest-cli

Start the Inngest Dev Server for local development:

# 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

The dev server will be available at http://localhost:8288 by default.

Configuration File (Optional)

Create inngest.json for complex setups:

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

Environment-Specific Setup

Local Development

INNGEST_DEV=1
# No keys required in dev mode

Production

INNGEST_EVENT_KEY=evt_your_production_event_key
INNGEST_SIGNING_KEY=signkey_your_production_signing_key

Custom Dev Server Port

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

If your app runs on a non-standard port (not 3000), make sure the dev server can reach it by specifying the URL with -u flag.

Common Issues & Solutions

Port Conflicts : If port 8288 is in use, specify a different port: -p 9999

Auto-discovery Not Working : Use manual URL specification: -u http://localhost:YOUR_PORT/api/inngest

Signature Verification Errors : Ensure INNGEST_SIGNING_KEY is set correctly in production

WebSocket Connection Issues : Verify Node.js version 22.4+ for connect mode

Docker Development : Use host.docker.internal for app URLs when running dev server in Docker

Next Steps

Create your first Inngest function with inngest.createFunction()
Test functions using the dev server's "Invoke" button
Send events with inngest.send() to trigger functions
Deploy to production with proper environment variables
See inngest-middleware for adding logging, error tracking, and other cross-cutting concerns
Monitor functions in the Inngest dashboard

The dev server automatically reloads when you change functions, making development fast and iterative.

Weekly Installs

273

Repository

inngest/inngest-skills

GitHub Stars

First Seen

Feb 17, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex262

opencode259

gemini-cli258

github-copilot258

amp256

kimi-cli256

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

140,500 周安装

signingKey : Signing key for production (prefer INNGEST_SIGNING_KEY env var). Moved from serve() to client in v4

signingKeyFallback : Fallback signing key for key rotation (prefer INNGEST_SIGNING_KEY_FALLBACK env var)

baseUrl : Custom Inngest API base URL (prefer INNGEST_BASE_URL env var)

logger : Custom logger instance (e.g. winston, pino) — enables logger in function context

middleware : Array of middleware (see inngest-middleware skill)