用途
@novu/framework 用于在代码中构建通知工作流,工作流与应用程序源码放在一起。内容用已有库渲染(React Email、Vue Email、Svelte Email),通过单一 HTTP 端点(Bridge)让 Novu Cloud 在执行时以来自服务的即时数据运行工作流。
适合:工作流必须进入源码控制或 GitOps;需要从数据库或 API 获取即时数据;需要用 React、Vue、Svelte Email 渲染邮件;需要执行自定义代码(LLM、第三方 API);需要类型化 payload 与步骤控制。
不适合:非技术同事维护全部内容、所有数据都能放进触发 payload、块编辑器已足够、只需纯发送流程或快速原型——这些情况可用 Dashboard 工作流。两种方式可在同一环境共存。
主要能力
- 用 workflow(...) 定义工作流,handler 接收 { step, payload, subscriber },按顺序调用步骤。
- 通道步骤:step.email(主题、正文、附件、from、replyTo)、step.sms、step.push、step.chat、step.inApp(返回 { seen, read, lastSeenDate, lastReadDate })。
- 动作步骤:step.delay(秒至月)、step.digest(按窗口或 cron 聚合,支持 digestKey;每个工作流仅一个 digest)、step.http(外部请求或 webhook,后续步骤引用响应数据时须声明 responseBodySchema)、step.custom(执行任意代码并持久化结果供后续步骤与 skip 使用)。
- 工作流选项:payloadSchema(Zod、JSON Schema 或 Class Validator)、name、description、tags、severity、critical、preferences。
- 步骤选项:controlSchema、skip、providers(按提供商覆盖请求,支持 _passthrough 深合并)、disableOutputSanitization。
- 控件(Controls):非技术同事可在 Dashboard 编辑的步骤级输入,由 schema 校验,值支持 LiquidJS 模板变量与过滤器;与 payload 的区别在于编辑者和持久化位置。
- 工作流偏好:在代码中定义默认通道偏好,all.readOnly 为 true 使工作流成为关键通知。
使用方式
- 引导项目:npx novu init --secret-key=<YOUR_NOVU_SECRET_KEY>;或在现有应用安装:npm install @novu/framework zod @react-email/components react-email,并设置 NOVU_SECRET_KEY。
- 用 workflow(...) 定义工作流并导出。
- 挂载 Bridge 端点(/api/novu):各框架提供 serve 包装器,涵盖 Next.js App/Pages Router、Express(需 express.json())、NestJS(NovuModule.register,依赖注入用 registerAsync)、Remix、SvelteKit、Nuxt、H3、AWS Lambda,也可用 NovuRequestHandler 自定义。
- 将 bridge URL 同步到 Novu Cloud(npx novu sync 或 GitHub Action)。
- 本地调试:npx novu@latest dev --port <YOUR_APP_PORT>,打开 http://localhost:2022 预览工作流、编辑控件、触发测试事件;Studio 会自动创建公共隧道。
执行链路:触发 → Novu Cloud Worker → 你的 Bridge(/api/novu)→ 提供商(SendGrid、FCM 等)。Bridge 负责发现工作流(GET)、解析步骤内容(POST)并校验 HMAC 签名。
限制与注意事项
- class-validator 方式需 class-validator、class-validator-jsonschema、reflect-metadata。
- JSON Schema 需 as const 才能推断 payload 类型。
- HTTP 步骤中只有 responseBodySchema 声明的属性可通过 {{ steps.<id>.<property> }} 引用。
- custom 步骤结果仅可用于后续步骤 resolver、providers 与 skip 函数,不能用于步骤控件。
- 每个工作流只能有一个 digest;需要两级 digest 时用 step.custom 串联第二个工作流。
- 工作流设计层面的决策(通道选择、严重级别、critical、digest 默认值、步骤条件、参考模板)在 design-workflow 中说明;本技能聚焦如何用代码表达。