--- title: Vite description: Set up your first durable workflow in a Vite application. docs_index: /llms.txt lastUpdated: 2026-10-13 type: guide summary: Set up Workflow SDK in a Vite 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 Vite app, run \`npm i workflow nitro\`. In \`vite.config.ts\`, import \`nitro\` from \`nitro/vite\`, \`workflow\` from \`workflow/vite\`, and configure \`plugins: \[nitro(), workflow()]\` plus \`nitro: \{ serverDir: "./" }\`. Add the TypeScript plugin \`\{ "name": "workflow" }\` to \`tsconfig.json\` if TypeScript is used. Create \`workflows/user-signup.ts\` with \`"use workflow"\`, \`sleep\`, and \`"use step"\` helpers. Add \`api/signup.post.ts\` using \`defineEventHandler\` from \`nitro/h3\` and \`start\` from \`workflow/api\`. Run \`npm run dev\`, call \`curl -X POST --json '\{"email":"hello\@example.com"}' http\://localhost:3000/api/signup\`, and inspect with \`npx workflow web\` or \`npx workflow inspect runs\`. This guide will walk through setting up your first workflow in a Vite app. Along the way, you'll learn more about the concepts that are fundamental to using the Workflow SDK in your own projects. *** ## 1. Create your Vite project Start by creating a new Vite project. This command will create a new directory named `my-workflow-app` with a minimal setup and setup a Vite project inside it. ```bash npm create vite@latest my-workflow-app -- --template react-ts ``` Enter the newly made directory: ```bash cd my-workflow-app ``` ### Install `workflow` and `nitro` ```bash npm i workflow nitro ``` ```bash pnpm add workflow nitro ``` ```bash yarn add workflow nitro ``` ```bash bun add workflow nitro ``` > While Vite provides the build tooling and development server, Nitro adds the server framework needed for API routes and deployment. Together they enable building full-stack applications with workflow support. Learn more about Nitro [here](https://v3.nitro.build). ### Configure Vite Add `workflow()` to your Vite config. This enables usage of the `"use workflow"` and `"use step"` directives. ```typescript title="vite.config.ts" lineNumbers import { nitro } from "nitro/vite"; import { defineConfig } from "vite"; import { workflow } from "workflow/vite"; export default defineConfig({ plugins: [nitro(), workflow()], // [!code highlight] nitro: { // [!code highlight] serverDir: "./", // [!code highlight] }, // [!code highlight] }); ``` ### Setup IntelliSense for TypeScript (Optional) To enable helpful hints in your IDE, setup 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); return { userId: user.id, status: "onboarded" }; } ``` We'll fill in those functions next. The current code does the following: - 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 have to add your workflow to a `POST` API route handler, `api/signup.post.ts` with the following code: ```typescript title="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 will trigger your workflow. > Workflows can be triggered from API routes or any server-side code. ## Run in development To start your development server, run the following command in your terminal in the Vite 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 Vite 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 `vite.config.ts` includes the `workflow/vite` plugin. 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)