--- title: Nitro description: Set up your first durable workflow in a Nitro v3 project. docs_index: /llms.txt lastUpdated: 2026-10-13 type: guide summary: Set up Workflow SDK in a Nitro app. prerequisites: - /docs/getting-started related: - /docs/foundations/workflows-and-steps --- > For an index of all documentation, see [/llms.txt](/llms.txt). **Prompt for coding agents** In this Nitro app, run \`npm i workflow\`. In \`nitro.config.ts\`, use \`defineConfig\` from \`nitro\`, set \`serverDir: "./server"\`, and add \`modules: \["workflow/nitro"]\`. Add the TypeScript plugin \`\{ "name": "workflow" }\` to \`tsconfig.json\` if TypeScript is used. Create \`workflows/user-signup.ts\` with \`handleUserSignup(email)\`, \`"use workflow"\`, \`sleep\` from \`workflow\`, and \`"use step"\` helpers. Add \`server/api/signup.post.ts\` using \`defineEventHandler\` from \`nitro/h3\` and \`start\` from \`workflow/api\` to start the workflow from \`\{ email }\`. Run \`npm run dev\`, call \`curl -X POST --json '\{"email":"hello\@example.com"}' http\://localhost:3000/api/signup\`, then inspect with \`npx workflow web\` or \`npx workflow inspect runs\`. ## 1. Create your Nitro project Create a [Nitro v3](https://v3.nitro.build/) project in a new directory named `nitro-app`: ```bash npx create-nitro-app ``` Enter the newly made directory: ```bash cd nitro-app ``` ### Install `workflow` ```bash npm i workflow ``` ```bash pnpm add workflow ``` ```bash yarn add workflow ``` ```bash bun add workflow ``` ### Configure Nitro Add the `workflow/nitro` module to your `nitro.config.ts`. This enables the `"use workflow"` and `"use step"` directives. ```typescript title="nitro.config.ts" lineNumbers import { defineConfig } from "nitro"; export default defineConfig({ serverDir: "./server", modules: ["workflow/nitro"], }); ``` ### Module options The `workflow/nitro` module reads its options from `workflow` on your Nitro config. ```typescript title="nitro.config.ts" lineNumbers import { defineConfig } from "nitro"; export default defineConfig({ modules: ["workflow/nitro"], workflow: { runtime: "nodejs22.x", sourcemap: "inline", }, }); ``` | Option | Type | Default | Description | | ----------- | --------------------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `dirs` | `string[]` | — | Directories to scan for workflows and steps. By default, `workflows/` is scanned from the project root and all layer source directories. | | `runtime` | `string` | `'nodejs22.x'` | Node.js runtime version for Vercel Functions (e.g. `'nodejs22.x'`, `'nodejs24.x'`). | | `sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` (dev) / `false` (prod) | Controls source maps on generated workflow bundles. Accepts the same values as esbuild's `sourcemap` option. Defaults to `'inline'` in development and `false` in production (smaller function bundles, which helps stay under the Vercel 250 MB function size limit). Set it explicitly, or use the `WORKFLOW_SOURCEMAP` environment variable, to override in either environment. | **Set up IntelliSense for TypeScript (optional)** To enable helpful hints in your IDE, set up the workflow plugin in `tsconfig.json`: ```json title="tsconfig.json" lineNumbers { "compilerOptions": { // ... rest of your TypeScript config "plugins": [ { "name": "workflow" // [!code highlight] } ] } } ``` ## 2. Create your first workflow Create a new file for our first workflow: ```typescript title="workflows/user-signup.ts" lineNumbers import { sleep } from "workflow"; export async function handleUserSignup(email: string) { "use workflow"; // [!code highlight] const user = await createUser(email); await sendWelcomeEmail(user); await sleep("5s"); // Pause for 5s - doesn't consume any resources await sendOnboardingEmail(user); console.log("Workflow is complete! Run 'npx workflow web' to inspect your run") return { userId: user.id, status: "onboarded" }; } ``` We'll fill in those functions next, but first review this code: - We define a **workflow** function with the directive `"use workflow"`. Think of the workflow function as the *orchestrator* of individual **steps**. - The Workflow SDK's `sleep` function allows us to suspend execution of the workflow without using up any resources. A sleep can be a few seconds, hours, days, or even months long. ## Create your workflow steps Define the missing functions. ```typescript title="workflows/user-signup.ts" lineNumbers import { FatalError } from "workflow"; // Our workflow function defined earlier async function createUser(email: string) { "use step"; // [!code highlight] console.log(`Creating user with email: ${email}`); // Full Node.js access - database calls, APIs, etc. return { id: crypto.randomUUID(), email }; } async function sendWelcomeEmail(user: { id: string; email: string }) { "use step"; // [!code highlight] console.log(`Sending welcome email to user: ${user.id}`); if (Math.random() < 0.3) { // By default, steps will be retried for unhandled errors throw new Error("Retryable!"); } } async function sendOnboardingEmail(user: { id: string; email: string }) { "use step"; // [!code highlight] if (!user.email.includes("@")) { // To skip retrying, throw a FatalError instead throw new FatalError("Invalid Email"); } console.log(`Sending onboarding email to user: ${user.id}`); } ``` Taking a look at this code: - Business logic lives inside **steps**. When a workflow invokes a step, the workflow suspends while the step runs with full Node.js access. The combined handler may execute it inline; queued retries and continuations return through the same flow route. - If a step throws an error, like in `sendWelcomeEmail`, the step will automatically be retried until it succeeds (or hits the step's max retry count). - Steps can throw a `FatalError` if an error is intentional and should not be retried. > We'll dive deeper into workflows, steps, and other ways to suspend or handle > events in [Foundations](/docs/foundations). ## 3. Create your route handler To invoke your new workflow, we'll create a new API route handler at `server/api/signup.post.ts` with the following code: ```typescript title="server/api/signup.post.ts" import { start } from "workflow/api"; import { defineEventHandler } from "nitro/h3"; import { handleUserSignup } from "../../workflows/user-signup"; export default defineEventHandler(async ({ req }) => { const { email } = await req.json() as { email: string }; // Executes asynchronously and doesn't block your app await start(handleUserSignup, [email]); return { message: "User signup workflow started", } }); ``` This route handler creates a `POST` request endpoint at `/api/signup` that triggers your workflow. > Workflows can be triggered from API routes or any server-side > code. ## 4. Run in development To start your development server, run the following command in your terminal in the Nitro root directory: ```bash npm run dev ``` Once your development server is running, you can trigger your workflow by running this command in the terminal: ```bash curl -X POST --json '{"email":"hello@example.com"}' http://localhost:3000/api/signup ``` Check the Nitro development server logs to see your workflow execute as well as the steps that are being processed. Additionally, you can use the [Workflow SDK CLI or Web UI](/docs/observability) to inspect your workflow runs and steps in detail. ```bash # Open the observability Web UI npx workflow web # or if you prefer a terminal interface, use the CLI inspect command npx workflow inspect runs ``` Workflow SDK Web UI ## Deploying to production Workflow SDK apps currently work best when deployed to [Vercel](https://vercel.com/home) and need no special configuration. Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere. ## Troubleshooting ### `start()` says it received an invalid workflow function If you see this error: ```text 'start' received an invalid workflow function. Ensure the Workflow SDK is configured correctly and the function includes a 'use workflow' directive. ``` Check both of these first: 1. The workflow function includes `"use workflow"`. 2. Your Nitro config includes the `workflow/nitro` module. See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes. ## Next steps - Learn more about the [Foundations](/docs/foundations). - Check [Errors](/docs/errors) if you encounter issues. - Explore the [API Reference](/docs/api-reference). --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)