inngest-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Inngest Setup

Inngest 配置

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.

本指南将从零开始在TypeScript项目中配置Inngest，涵盖安装、客户端配置、连接模式以及本地开发等内容。

本指南专注于TypeScript。如果使用Python或Go，请参考Inngest官方文档获取对应语言的指导。核心概念适用于所有语言。

Prerequisites

前置条件

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

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

Step 1: Install the Inngest SDK

步骤1：安装Inngest SDK

Install the

inngest

npm package in your project:

bash

npm install inngest

在你的项目中安装

inngest

npm包：

bash

npm install inngest

or

yarn add inngest

or

pnpm add inngest

or

bun add inngest

undefined

bun add inngest

undefined

Step 2: Create an Inngest Client

步骤2：创建Inngest客户端

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

typescript

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

export const inngest = new Inngest({
  id: "my-app" // Unique identifier for your application (hyphenated slug)
});

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

typescript

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

export const inngest = new Inngest({
  id: "my-app" // 你的应用唯一标识符（使用连字符分隔的短名称）
});

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
```
)
schemas
: Event payload types for TypeScript typing

id
（必填）：应用的唯一标识符。使用类似
```
"my-app"
```
或
```
"user-service"
```
的连字符短名称
eventKey
：用于发送事件的密钥（推荐使用
```
INNGEST_EVENT_KEY
```
环境变量）
env
：分支环境的环境名称
isDev
：强制开启开发模式（
```
true
```
）或云模式（
```
false
```
）
schemas
：用于TypeScript类型校验的事件负载类型

Environment Variables Setup

环境变量配置

Set these environment variables in your

.env

file or deployment environment:

env

undefined

在你的

.env

文件或部署环境中设置以下环境变量：

env

undefined

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)

可选 - 自定义开发服务器URL（默认：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`.

INNGEST_BASE_URL=http://localhost:8288


**⚠️ 常见误区**：永远不要在源代码中硬编码密钥。请始终使用环境变量存储`INNGEST_EVENT_KEY`和`INNGEST_SIGNING_KEY`。

Step 3: Choose Your Connection Mode

步骤3：选择连接模式

Inngest supports two connection modes:

Inngest支持两种连接模式：

Mode A: Serve Endpoint (HTTP)

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

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

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

Mode B: Connect (WebSocket)

模式B：作为Worker连接（WebSocket模式）

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

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

Step 4A: Serving an Endpoint (HTTP Mode)

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

Create an API endpoint that exposes your functions to Inngest:

typescript

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

typescript

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

typescript

// 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()); // Required for Inngest

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

🔧 Framework-Specific Notes:

Express: Must use
```
express.json()
```
middleware. Set the limit option greater than
```
100kb
```
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

⚠️ 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.

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

typescript

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

typescript

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

typescript

// 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()); // Inngest必填

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

🔧 框架特定说明：

Express：必须使用
```
express.json()
```
中间件。设置大于
```
100kb
```
的限制选项以支持更大的函数状态。
Fastify：使用
```
inngest/fastify
```
中的
```
fastifyPlugin
```
Cloudflare Workers：使用
```
inngest/cloudflare
```
AWS Lambda：使用
```
inngest/lambda
```
其他框架，请查看此处的
```
serve
```
参考文档：https://www.inngest.com/docs-markdown/learn/serving-inngest-functions

⚠️ 常见误区：请始终使用

/api/inngest

作为端点路径，这将启用自动发现功能。如果必须使用其他路径，你需要通过

-u

标志手动配置发现。

Step 4B: Connect as Worker (WebSocket Mode)

步骤4B：作为Worker连接（WebSocket模式）

For long-running applications that maintain persistent connections:

typescript

// 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

适用于长期运行并保持持久连接的应用：

typescript

// 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已连接:", connection.state);

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

连接模式要求：

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

Step 5: Organizing with Apps

步骤5：按应用组织函数

As your system grows, organize functions into logical apps:

typescript

// 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.

随着系统规模增长，将函数按逻辑应用分组：

typescript

// 用户服务
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一致。

Step 6: Local Development with inngest-cli

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

Start the Inngest Dev Server for local development:

bash

undefined

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

bash

undefined

Auto-discover your app on common ports/endpoints

自动发现常见端口/端点上的应用

npx --ignore-scripts=false inngest-cli@latest dev

Specify your app's URL manually

手动指定应用的URL

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.

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


开发服务器默认在`http://localhost:8288`可用。

Configuration File (Optional)

配置文件（可选）

Create

inngest.json

for complex setups:

json

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

创建

inngest.json

用于复杂配置：

json

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

Environment-Specific Setup

环境特定配置

Local Development

本地开发

env

INNGEST_DEV=1

env

INNGEST_DEV=1

No keys required in dev mode

开发模式下无需密钥

undefined

undefined

Production

生产环境

env

INNGEST_EVENT_KEY=evt_your_production_event_key
INNGEST_SIGNING_KEY=signkey_your_production_signing_key

env

INNGEST_EVENT_KEY=evt_your_production_event_key
INNGEST_SIGNING_KEY=signkey_your_production_signing_key

Custom Dev Server Port

自定义开发服务器端口

env

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.

env

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

如果你的应用运行在非标准端口（不是3000），请确保通过

-u

标志指定URL，使开发服务器能够访问它。

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

端口冲突：如果端口8288已被占用，指定其他端口：

-p 9999

自动发现失败：使用手动URL指定：

-u http://localhost:YOUR_PORT/api/inngest

签名验证错误：确保生产环境中

INNGEST_SIGNING_KEY

设置正确

WebSocket连接问题：验证连接模式使用的Node.js版本为22.4+

Docker开发：当在Docker中运行开发服务器时，使用

host.docker.internal

作为应用URL

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.

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

开发服务器会在你修改函数时自动重新加载，使开发过程快速且迭代高效。