inngest-nextjs-patterns

Inngest + Next.js 模式

在 Next.js App Router 项目中使用 Inngest 构建事件驱动、持久化后台任务的模板和约定。本技能遵循 Inngest 官方文档所用的约定（分散式 eventType() schema、kebab-case 稳定函数 ID、幂等步骤），确保重试、重放和并发控制真正按预期工作。

适用场景

遇到以下情况时，请阅读本技能：

• 首次在 Next.js 应用中设置 Inngest（客户端 + 路由处理程序 + 第一个函数）
• 向 Next.js 应用添加新的后台作业、webhook 处理程序或定时任务
• 定义供其他函数触发的新领域事件
• 编排必须能在进程重启后继续执行的多步骤任务（持久化工作流、Saga）
• 检查现有 Inngest 代码中的事件命名、步骤幂等性或稳定函数 ID
• 从 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 单例客户端。每个应用只生成一次。
route-handler.ts.template	src/app/api/inngest/route.ts	一次性设置：Inngest 调用函数时访问的 App Router 端点。每个应用只生成一次。
event.ts.template	src/inngest/events/{domain}.ts	定义新的类型化事件（带有 Zod schema），供生产者发送、函数消费。
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	接收一个事件并分发任务的编排器——通过 step.sendEvent（触发后不等待）或 Promise.all(step.invoke(...))（等待结果）实现。

快速参考

• 事件名称形式： domain/entity.verb_past——例如 app/user.created、shop/order.placed、billing/invoice.paid。完整规则请参阅约定文档。
• 函数 id： 使用稳定的 kebab-case，部署后绝不要重命名——Inngest 将其用作持久化状态键。
• 步骤 id： 使用描述性的 kebab-case，同样具有持久性；更改后，重放时该步骤会重新运行。
• 幂等性： 每个 step.run 都必须能够安全重试。如果它调用会修改状态的第三方 API，请传入幂等键。
• 开发服务器： 运行 npx inngest-cli@latest dev，然后在 http://localhost:8288 打开 UI。在 .env.local 中设置 INNGEST_DEV=1，让 SDK 连接到该开发服务器。

项目布局假设

模板假设项目使用带有 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 — Inngest 的 serve() 适配器默认作为 Vercel Serverless Function 运行；AI SDK 技能说明了 Fluid Compute 和长时间运行 Agent 时延长超时的相关内容。