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 realti

Inngest v3 to 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. When to Trigger Use this skill for requests like: "Upgrade Inngest from v3 to v4" "Fix our Inngest v4 migration" "We're getting signing key required / cloud mode errors after upgrading" " step.invoke with a string function ID stopped working" " @inngest/realtime broke after installing inngest@4 " "Move from EventSchemas to eventType" "Make this existing Inngest repo v4 compatible" 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. Migration Scan Start by locating all Inngest surfaces: Then classify the repo: No Inngest yet: use inngest setup , not this migration skill. v3 only: migrate the SDK and all breaking changes together. mixed v3/v4: prioritize removing broken v3 APIs from v4 code. v4 mostly done: focus on missed runtime gotchas like local dev mode, serverless maxRuntime , realtime package imports, and string step.invoke . Before editing, record: Upgrade Order 1. Update package versions. 2. Fix client construction and local/prod mode. 3. Move serve options to the client. 4. Move triggers into createFunction options. 5. Replace EventSchemas with eventType() / staticSchema() . 6. Rewrite step.invoke() string IDs. 7. Migrate realtime from @inngest/realtime to v4 native APIs. 8. Update middleware and logging. 9. Configure checkpointing/serverless runtime. 10. Typecheck, run tests, and optionally sync with the dev server. Package and Environment 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 . Client and Serve Options 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 serveOrigin streaming: "force" streaming: true streaming: "allow" streaming: true streaming: false stays false logLevel is removed; pass a logger such as new ConsoleLogger({ level }) createFunction Triggers 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. EventSchemas to eventType/staticSchema 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. step.invoke 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: Realtime Migration v3 realtime used @inngest/realtime and middleware injected publish . v4 realtime is native. Replace: @inngest/realtime package realtimeMiddleware() handler args such as { publish } v3 React hooks such as useInngestSubscription() With: channel definitions from inngest/realtime step.realtime.publish between steps inngest.realtime.publish inside an existing step.run subscription helpers/hooks from current v4 APIs Use 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. Parallelism and Checkpointing 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. Connect Changes If the repo uses Connect: rewriteGatewayEndpoint is replaced by gatewayUrl . Connect may use worker thread isolation. If integration issues appear, check isolateExecution: false or INNGEST CONNECT ISOLATE EXECUTION=false . Keep target URLs and signing/event keys in env vars. Verification Run checks in increasing confidence: 1. Package manager install/update. 2. Typecheck. 3. Unit/integration tests around migrated functions. 4. Start the app with INNGEST DEV=1 . 5. Run npx inngest cli@latest dev and confirm function discovery. 6. Send one representative event and inspect the run. If local dev server verification is not possible, state exactly which static checks passed and what runtime verification remains. Common Failure Messages "A signing key is required to run in Cloud mode" : set 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() . Type errors around schemas : replace EventSchemas with eventType() and staticSchema() . Unexpected Promise.race behavior : use group.parallel() for first winner step races or disable optimized parallelism only when necessary. Anti Patterns Mixing v3 realtime middleware with inngest@4 . Passing signingKey , baseUrl , or signingKeyFallback to serve() . Moving event trigger syntax but forgetting cron/invoke triggered functions. Replacing EventSchemas with untyped string events everywhere. Hardcoding isDev: true in production bound source. Leaving string IDs in step.invoke . Skipping typecheck after mechanical migration.

inngest-v3-v4-migration