OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add inngest/inngest-skills --skill inngest-v3-v4-migration
Use when upgrading an existing TypeScript codebase from Inngest SDK v3 to v4, or when fixing mixed v3/v4 API usage. Covers detecting current SDK usage, moving triggers into createFunction options, replacing EventSchemas with eventType/staticSchema, moving serve options to the client, updating realtime imports, rewriting step.invoke string IDs, checkpointing/serverless runtime settings, Connect option changes, and verification.
npx skills add inngest/inngest-skills --skill inngest-v3-v4-migration
Use this skill when the user asks to upgrade Inngest, fix v3/v4 errors, migrate realtime, or clean up a codebase that has mixed SDK patterns.
Primary reference: https://www.inngest.com/docs/reference/typescript/v4/migrations/v3-to-v4
This skill is agent-first: detect actual usage first, make mechanical API changes in a controlled order, then typecheck and run focused tests.
Use this skill for requests like:
step.invoke with a string function ID stopped working"@inngest/realtime broke after installing inngest@4"If the user asks for a broad codebase reliability audit first, use
inngest-brownfield-audit to choose scope, then return here for the v4 changes.
Start by locating all Inngest surfaces:
Then classify the repo:
inngest-setup, not this migration skill.maxRuntime, realtime package imports, and string step.invoke.Before editing, record:
createFunction options.EventSchemas with eventType() / staticSchema().step.invoke() string IDs.@inngest/realtime to v4 native APIs.Install the latest v4 SDK:
If the repo uses v3 realtime, remove @inngest/realtime; v4 realtime lives in
the inngest package and subpaths such as inngest/realtime, inngest/react,
and native step.realtime / inngest.realtime.
v4 defaults to Cloud mode. For local development, use an env var:
Do not hardcode isDev: true in source unless the repo's existing environment
pattern clearly scopes it to local-only code. Production should use
INNGEST_SIGNING_KEY.
In v4, options such as signingKey, signingKeyFallback, and baseUrl belong
on new Inngest(...), not on serve(...).
If the repo already relies on supported environment variables and does not pass serve options explicitly, no code change may be required for those keys.
Other renames:
serveHost -> serveOriginstreaming: "force" -> streaming: truestreaming: "allow" -> streaming: truestreaming: false stays falselogLevel is removed; pass a logger such as new ConsoleLogger({ level })Triggers move into the first argument's options object.
Cron triggers move the same way:
If a function is invoked only via step.invoke, it may be triggerless.
Replace centralized EventSchemas with event-specific definitions.
Use event types consistently:
Important: staticSchema expects a type, not an interface. Convert interfaces
to type aliases when needed.
v4 no longer accepts raw string function IDs. Use an imported function
reference or referenceFunction().
If the target function is in the same codebase, prefer passing the imported function itself:
v3 realtime used @inngest/realtime and middleware-injected publish.
v4 realtime is native.
Replace:
@inngest/realtime packagerealtimeMiddleware(){ publish }useInngestSubscription()With:
inngest/realtimestep.realtime.publish between stepsinngest.realtime.publish inside an existing step.runUse inngest-realtime for detailed patterns. Do not call
step.realtime.publish from inside step.run; use inngest.realtime.publish
there to avoid step-in-step behavior.
v4 enables optimized parallelism and checkpointing by default.
Watch for Promise.race over steps. With optimized parallelism, Promise.race
waits for all step promises to settle. If the repo relies on first-winner
behavior, use group.parallel().
For serverless platforms, configure checkpointing maxRuntime slightly below
the platform limit:
On Vercel or similar frameworks, also set the route handler's max duration where the platform supports it.
If the repo uses Connect:
rewriteGatewayEndpoint is replaced by gatewayUrl.isolateExecution: false or INNGEST_CONNECT_ISOLATE_EXECUTION=false.Run checks in increasing confidence:
INNGEST_DEV=1.npx inngest-cli@latest dev and confirm function discovery.If local dev-server verification is not possible, state exactly which static checks passed and what runtime verification remains.
INNGEST_DEV=1 for
local development or configure INNGEST_SIGNING_KEY for production.Cls is not a constructor on /api/inngest: likely v3
@inngest/realtime middleware in a v4 app. Remove the package and migrate to
native realtime.step.invoke fails with string function ID: replace strings with
imported function references or referenceFunction().EventSchemas with eventType() and
staticSchema().Promise.race behavior: use group.parallel() for first-winner
step races or disable optimized parallelism only when necessary.inngest@4.signingKey, baseUrl, or signingKeyFallback to serve().EventSchemas with untyped string events everywhere.isDev: true in production-bound source.step.invoke.Inngest migration scan:
- Current package versions:
- Client files:
- Serve/connect entrypoints:
- Functions using old trigger syntax:
- EventSchemas usage:
- Realtime v3 package usage:
- step.invoke string IDs:
- Serverless runtime constraints:
- Tests/checks available:npm install inngest@latest
# or pnpm add inngest@latest
# or yarn add inngest@latestINNGEST_DEV=1 npm run dev// Old v3
app.use(
"/api/inngest",
serve({
client: inngest,
functions,
signingKey: process.env.INNGEST_SIGNING_KEY,
baseUrl: process.env.INNGEST_BASE_URL,
})
);
// New v4
export const inngest = new Inngest({
id: "my-app",
signingKey: process.env.INNGEST_SIGNING_KEY,
baseUrl: process.env.INNGEST_BASE_URL,
});
app.use("/api/inngest", serve({ client: inngest, functions }));// Old v3
inngest.createFunction(
{ id: "send-welcome" },
{ event: "user/created" },
async ({ event, step }) => {}
);
// New v4
inngest.createFunction(
{ id: "send-welcome", triggers: [{ event: "user/created" }] },
async ({ event, step }) => {}
);inngest.createFunction(
{ id: "nightly-sync", triggers: [{ cron: "0 2 * * *" }] },
async ({ step }) => {}
);import { Inngest, eventType, staticSchema } from "inngest";
import { z } from "zod";
export const userCreated = eventType("user/created", {
schema: z.object({
userId: z.string(),
email: z.string().email(),
}),
});
type InvoicePaid = {
invoiceId: string;
customerId: string;
};
export const invoicePaid = eventType("billing/invoice.paid", {
schema: staticSchema<InvoicePaid>(),
});await inngest.send(userCreated.create({ userId, email }));
inngest.createFunction(
{ id: "on-user-created", triggers: [userCreated] },
async ({ event }) => {}
);
await step.waitForEvent("wait-for-invoice", {
event: invoicePaid,
timeout: "7d",
});import { referenceFunction } from "inngest";
await step.invoke("run-report", {
function: referenceFunction({
appId: "analytics-app",
functionId: "generate-report",
}),
data: { reportId },
});await step.invoke("run-report", {
function: generateReport,
data: { reportId },
});export const inngest = new Inngest({
id: "my-app",
checkpointing: {
maxRuntime: "50s",
},
});