workflow 5.0.0-beta.4 → 5.0.0-beta.40

package/docs/getting-started/nestjs.mdx

@@ -9,10 +9,15 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
+<CopyPrompt
+  text="In this NestJS app, run `npm i workflow @workflow/nest` and `npm i -D @swc/cli @swc/core`. Configure `nest-cli.json` with `compilerOptions.builder: &quot;swc&quot;` and `deleteOutDir: true`. Run `npx @workflow/nest init`, add `.swcrc` to `.gitignore`, and set package scripts `prebuild: &quot;npx @workflow/nest init --force&quot;` and `start:dev: &quot;npx @workflow/nest init --force && nest start --watch&quot;`. Import `WorkflowModule.forRoot()` from `@workflow/nest` in `src/app.module.ts` (use `{ moduleType: &quot;commonjs&quot;, distDir: &quot;dist&quot; }` if compiling CommonJS). Create `src/workflows/user-signup.ts` with `&quot;use workflow&quot;`, `sleep`, and `&quot;use step&quot;` helpers. Add a `POST /signup` controller method that reads `email`, calls `start(handleUserSignup, [email])` from `workflow/api`, and returns JSON. Run `npm run start:dev`, call `curl -X POST --json '{&quot;email&quot;:&quot;hello@example.com&quot;}' http://localhost:3000/signup`, and inspect with `npx workflow web` or `npx workflow inspect runs`."
+/>
+
 This guide will walk through setting up your first workflow in a NestJS app. Along the way, you'll learn more about the concepts that are fundamental to using the Workflow SDK in your own projects.
 
 <Callout>
-NestJS integration is experimental and not yet supported for deployment to Vercel.
+NestJS integration is experimental. Deployment to Vercel is supported via the
+`workflow-nest build --vercel` command — see [Deploy to Vercel](#deploy-to-vercel) below.
 </Callout>
 
 ---
@@ -284,7 +289,7 @@ async function sendOnboardingEmail(user: { id: string; email: string }) {
 
 Taking a look at this code:
 
-- Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+- 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.
 
@@ -357,6 +362,66 @@ npx workflow inspect runs
 
 </Step>
 
+<Step>
+
+## Deploy to Vercel
+
+Because NestJS is not a Vercel-native framework, the Workflow SDK produces a
+[Build Output API](https://vercel.com/docs/build-output-api) directory for you. This emits the
+workflow queue-consumer function (registered with `experimentalTriggers` so Vercel's queue can
+discover it) alongside your NestJS app as a catch-all function. Without it, workflow runs stay
+`pending` because nothing consumes the queue.
+
+Add a Vercel-specific entry module that default-exports your Nest app's underlying Node handler:
+
+```typescript title="_vercel/entry.ts" lineNumbers
+import 'reflect-metadata';
+import { NestFactory } from '@nestjs/core';
+import type { NestExpressApplication } from '@nestjs/platform-express';
+import express from 'express';
+import { AppModule } from '../dist/app.module.js';
+
+let ready: Promise<express.Express> | undefined;
+
+async function createHandler() {
+  const app = await NestFactory.create<NestExpressApplication>(AppModule, {
+    bodyParser: false,
+  });
+  app.use(express.json());
+  await app.init();
+  return app.getHttpAdapter().getInstance();
+}
+
+export default async function handler(req: express.Request, res: express.Response) {
+  ready ??= createHandler();
+  return (await ready)(req, res);
+}
+```
+
+Skip the in-process build on Vercel (the bundles are pre-built) by passing `skipBuild` when
+`VERCEL` is set:
+
+{/* @skip-typecheck - config snippet, WorkflowModule imported above */}
+```typescript title="src/app.module.ts"
+WorkflowModule.forRoot({ skipBuild: Boolean(process.env.VERCEL) });
+```
+
+Then set your build command so the Build Output is produced after `nest build`:
+
+```json title="package.json" lineNumbers
+{
+  "scripts": {
+    "vercel-build": "workflow-nest init --force && nest build && workflow-nest build --vercel --dirs src/workflows --entry _vercel/entry.ts"
+  }
+}
+```
+
+Deploy as usual. `workflow-nest build --vercel` runs automatically on Vercel (it also detects the
+`VERCEL` environment variable), writing `.vercel/output` with the consumer function so your runs
+execute instead of staying `pending`.
+
+</Step>
+
 </Steps>
 
 ---
@@ -386,6 +451,15 @@ WorkflowModule.forRoot({
   // Only used when moduleType is 'commonjs'
   // Should match the outDir in your tsconfig.json
   distDir: 'dist',
+
+  // Source maps on generated workflow bundles (default: 'inline' in
+  // development, false in production).
+  // Accepts the same values as esbuild's sourcemap option: true, false,
+  // 'inline', 'linked', 'external', 'both'. Set to false for smaller
+  // function bundles (useful for staying under the Vercel 250MB function
+  // size limit) at the cost of stack traces pointing at generated code.
+  // Can also be set via the WORKFLOW_SOURCEMAP environment variable.
+  sourcemap: 'inline',
 });
 ```
 
@@ -396,7 +470,7 @@ WorkflowModule.forRoot({
 If you see this error:
 
 ```
-'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.
+'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:

package/docs/getting-started/next.mdx

@@ -7,9 +7,13 @@ prerequisites:
   - /docs/getting-started
 related:
   - /docs/api-reference/workflow-next
-  - /docs/deploying/world/vercel-world
+  - /worlds/vercel
 ---
 
+<CopyPrompt
+  text="In this Next.js app, run `npm i workflow`. Wrap `next.config.ts` with `withWorkflow` from `workflow/next`. If the app has `proxy.ts` or middleware, exclude `.well-known/workflow/` from its matcher. Add `workflows/user-signup.ts` exporting `handleUserSignup(email)` with `&quot;use workflow&quot;`, `sleep` from `workflow`, and `&quot;use step&quot;` helper functions that create a user, send a welcome email, and send an onboarding email. Add `app/api/signup/route.ts` with a POST handler that reads `{ email }`, calls `start(handleUserSignup, [email])` from `workflow/api`, and returns JSON. Run `npm run dev`, trigger `curl -X POST --json '{&quot;email&quot;:&quot;hello@example.com&quot;}' http://localhost:3000/api/signup`, and inspect with `npx workflow web` or `npx workflow inspect runs`."
+/>
+
 <Steps>
 
 <Step>
@@ -75,9 +79,9 @@ To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json
 </Accordion>
 
 <Accordion type="single" collapsible>
-  <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
+  <AccordionItem value="configure-proxy-handler" className="[&_h3]:my-0">
     <AccordionTrigger className="text-sm">
-      ### Configure Proxy Handler (if applicable)
+      <h3 id="configure-proxy-handler">Configure Proxy Handler (if applicable)</h3>
     </AccordionTrigger>
     <AccordionContent className="[&_p]:my-2">
 
@@ -85,7 +89,9 @@ If your Next.js app has a [proxy handler](https://nextjs.org/docs/app/api-refere
 (formerly known as "middleware"), you'll need to update the matcher pattern to exclude Workflow's
 internal paths to prevent the proxy handler from running on them.
 
-Add `.well-known/workflow/*` to your middleware's exclusion list:
+If you see `[local world] Queue operation failed` with `Cannot perform ArrayBuffer.prototype.slice on a detached ArrayBuffer`, your proxy matcher is still intercepting Workflow's internal `POST /.well-known/workflow/v1/flow` request. This is especially easy to miss in Next.js 16, where `proxy.ts` replaced `middleware.ts`.
+
+Add `.well-known/workflow/*` to your matcher exclusion list:
 
 ```typescript title="proxy.ts" lineNumbers
 import { NextResponse } from "next/server";
@@ -186,7 +192,7 @@ async function sendOnboardingEmail(user: { id: string; email: string}) {
 
 Taking a look at this code:
 
-* Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+* 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.
 
@@ -310,7 +316,7 @@ Without this configuration, you may experience intermittent issues where workflo
 If you see this error:
 
 ```
-'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.
+'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:

package/docs/getting-started/nitro.mdx

@@ -9,6 +9,10 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
+<CopyPrompt
+  text="In this Nitro app, run `npm i workflow`. In `nitro.config.ts`, use `defineConfig` from `nitro`, set `serverDir: &quot;./server&quot;`, and add `modules: [&quot;workflow/nitro&quot;]`. Add the TypeScript plugin `{ &quot;name&quot;: &quot;workflow&quot; }` to `tsconfig.json` if TypeScript is used. Create `workflows/user-signup.ts` with `handleUserSignup(email)`, `&quot;use workflow&quot;`, `sleep` from `workflow`, and `&quot;use step&quot;` 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 '{&quot;email&quot;:&quot;hello@example.com&quot;}' http://localhost:3000/api/signup`, then inspect with `npx workflow web` or `npx workflow inspect runs`."
+/>
+
 <Steps>
 
 <Step>
@@ -46,6 +50,28 @@ export default defineConfig({
 
 ```
 
+### 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 — helps stay under the Vercel 250MB function size limit). Set it explicitly, or use the `WORKFLOW_SOURCEMAP` environment variable, to override in either environment. |
+
 <Accordion type="single" collapsible>
   <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
     <AccordionTrigger className="[&_p]:my-0 text-lg [&_p]:text-foreground">
@@ -146,7 +172,7 @@ async function sendOnboardingEmail(user: { id: string; email: string }) {
 
 Taking a look at this code:
 
-- Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+- 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.
 
@@ -235,7 +261,7 @@ Check the [Deploying](/docs/deploying) section to learn how your workflows can b
 If you see this error:
 
 ```
-'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.
+'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:

package/docs/getting-started/nuxt.mdx

@@ -9,6 +9,10 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
+<CopyPrompt
+  text="In this Nuxt app, run `npm i workflow`. In `nuxt.config.ts`, add `modules: [&quot;workflow/nuxt&quot;]` and keep `compatibilityDate: &quot;latest&quot;`. Create `workflows/user-signup.ts` exporting `handleUserSignup(email)` with `&quot;use workflow&quot;`, `sleep` from `workflow`, and `&quot;use step&quot;` helpers that create a user and send emails. Add `server/api/signup.post.ts` using `defineEventHandler` from `h3` or `nitro/h3` and `start` from `workflow/api` to read `{ email }` and start the workflow. Run `npm run dev`, call `curl -X POST --json '{&quot;email&quot;:&quot;hello@example.com&quot;}' http://localhost:3000/api/signup`, and inspect with `npx workflow web` or `npx workflow inspect runs`."
+/>
+
 <Steps>
 
 <Step>
@@ -145,7 +149,7 @@ async function sendOnboardingEmail(user: { id: string; email: string }) {
 
 Taking a look at this code:
 
-- Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+- 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.
 
@@ -236,7 +240,7 @@ Check the [Deploying](/docs/deploying) section to learn how your workflows can b
 If you see this error:
 
 ```
-'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.
+'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:

package/docs/getting-started/python.mdx

@@ -10,34 +10,31 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
+<CopyPrompt
+  text="In this Python project, add `requires-python = &quot;&gt;=3.12&quot;` and `dependencies = [&quot;vercel&quot;]` under `[project]` in `pyproject.toml`. Add `[[tool.vercel.workflows]]` with `entrypoint = &quot;app.workflows:wf&quot;`. Create `app/workflow.py` with `from vercel import workflow` and `wf = workflow.Workflows()`. Create `app/workflows/ai_content_workflow.py` importing `wf`, define `@wf.workflow async def ai_content_workflow(*, topic: str)`, and call step functions such as `generate_draft` and `summarize_draft`. Export `wf` from `app/workflows/__init__.py` and import the workflow module so its definitions are registered. Mark step functions with `@wf.step`, use `await workflow.sleep(&quot;7 days&quot;)` for durable delays where needed, and use a `workflow.BaseHook` Pydantic model plus `.wait(token=...)` and `.resume(token)` for external approval events. Verify the workflow entrypoint uses the `module:object` format and points to the exported `Workflows` registry."
+/>
+
 <Callout type="warn">
-The Python SDK is currently in **beta**. APIs and behavior may change. For the latest documentation and updates, see the [official Vercel Workflow Python documentation](https://vercel.com/docs/workflow/python?language=py).
+The Python SDK is currently in **beta**. APIs and behavior may change. For the latest documentation and updates, see the [official Vercel Workflow Python documentation](https://vercel.com/docs/workflows/python).
 </Callout>
 
 You can build durable workflows in Python using the [`vercel` Python SDK](https://pypi.org/project/vercel/). Your workflow code can pause, resume, and maintain state, just like the JavaScript and TypeScript Workflow SDK.
 
 ## Getting Started
 
-Install the `vercel` package:
-
-```bash filename="Terminal"
-pip install vercel
-```
+Add the `vercel` package and workflow entrypoint to `pyproject.toml`:
 
-Configure `experimentalServices` in your `vercel.json`:
+```toml filename="pyproject.toml"
+[project]
+requires-python = ">=3.12"
+dependencies = ["vercel"]
 
-```json filename="vercel.json"
-{
-  "experimentalServices": {
-    "ai_content_workflow": {
-      "type": "worker",
-      "entrypoint": "app/workflows/ai_content_workflow.py",
-      "topics": ["__wkf_*"]
-    }
-  }
-}
+[[tool.vercel.workflows]]
+entrypoint = "app.workflows:wf"
 ```
 
+The workflow `entrypoint` uses the `module:object` format and points to the exported `Workflows` registry.
+
 ## Workflows
 
 A workflow is a stateful function that coordinates multi-step logic over time. Create a `Workflows` instance and use the `@wf.workflow` decorator to mark a function as durable:
@@ -62,6 +59,15 @@ async def ai_content_workflow(*, topic: str):
     }
 ```
 
+Export the registry from the workflow package and import the module containing your workflow so its definitions are registered:
+
+```python filename="app/workflows/__init__.py"
+from app.workflow import wf
+from app.workflows import ai_content_workflow
+
+__all__ = ["ai_content_workflow", "wf"]
+```
+
 Under the hood, the workflow compiles into a route that orchestrates execution. All inputs and outputs are recorded in an event log. If a deploy or crash happens, the system replays execution deterministically from where it stopped.
 
 ## Steps
@@ -156,7 +162,7 @@ When a hook receives data, the workflow resumes automatically. You don&apos;t ne
 
 ## Learn More
 
-For comprehensive documentation, examples, and the latest updates, visit the [official Vercel Workflow Python documentation](https://vercel.com/docs/workflow/python).
+For comprehensive documentation, examples, and the latest updates, visit the [official Vercel Workflow Python documentation](https://vercel.com/docs/workflows/python).
 
 ## Next Steps
 

package/docs/getting-started/react-router/index.mdx

@@ -0,0 +1,33 @@
+---
+title: React Router
+description: Run durable workflows in a React Router framework-mode app using Nitro.
+type: overview
+summary: Choose your React Router version and connect React Router, Nitro, and Workflow SDK.
+related:
+  - /docs/getting-started/nitro
+  - /docs/getting-started/vite
+  - /docs/foundations/workflows-and-steps
+---
+
+React Router framework mode builds the browser application and its server-rendering code, but it still needs a server to receive requests. [Nitro](https://v3.nitro.build) provides that server. Workflow SDK integrates with Nitro to add the durable workflow routes and build artifacts.
+
+The three pieces share one Vite build:
+
+1. **React Router** builds your routes, loaders, actions, and browser assets.
+2. **Nitro** runs the React Router request handler and any routes in `server/routes`.
+3. **Workflow SDK** finds files with `"use workflow"` and `"use step"`, then adds its runtime routes to Nitro.
+
+Choose the guide that matches your React Router major version:
+
+<AutoCards />
+
+<Callout>
+  These guides require **Nitro v3**. Nitro v2 does not provide the Vite
+  environment integration used by this setup.
+</Callout>
+
+## What the bridge does
+
+The setup adds a small `server/ssr.ts` file. It turns React Router's generated server build into a standard Fetch API handler that Nitro can run. The Vite config then points Nitro's server and public output at the same `build` directory React Router uses.
+
+This is configuration in your application, not a separate React Router adapter. Your React Router routes remain React Router routes, while Nitro owns the HTTP server and Workflow SDK uses Nitro's lifecycle and routing.

package/docs/getting-started/react-router/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "React Router",
+  "pages": ["v7", "v8"],
+  "defaultOpen": true
+}

package/docs/getting-started/react-router/v7.mdx

@@ -0,0 +1,237 @@
+---
+title: React Router v7
+description: Add durable workflows to a React Router v7 framework-mode app using Nitro v3.
+type: guide
+summary: Enable the Vite Environment API and configure React Router v7, Nitro v3, and Workflow SDK.
+prerequisites:
+  - /docs/getting-started/react-router
+related:
+  - /docs/getting-started/nitro
+  - /docs/foundations/workflows-and-steps
+---
+
+This guide starts with an existing React Router v7 framework-mode app. It is verified with v7.18.1; if your config does not recognize `v8_viteEnvironmentApi`, update to the latest v7 release.
+
+<Steps>
+
+<Step>
+
+## Install Nitro and Workflow SDK
+
+<Tabs items={["npm", "pnpm", "bun", "yarn"]} defaultValue="pnpm">
+
+<Tab value="npm">
+
+```bash
+npm install nitro workflow
+```
+
+</Tab>
+
+<Tab value="pnpm">
+
+```bash
+pnpm add nitro workflow
+```
+
+</Tab>
+
+<Tab value="bun">
+
+```bash
+bun add nitro workflow
+```
+
+</Tab>
+
+<Tab value="yarn">
+
+```bash
+yarn add nitro workflow
+```
+
+</Tab>
+
+</Tabs>
+
+This integration requires Nitro v3.
+
+</Step>
+
+<Step>
+
+## Enable the Vite Environment API
+
+React Router v7 keeps the Vite Environment API behind a future flag. Enable the required flag and set an explicit build directory:
+
+```typescript title="react-router.config.ts" lineNumbers
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  ssr: true,
+  buildDirectory: "build", // [!code highlight]
+  future: {
+    v8_viteEnvironmentApi: true, // [!code highlight]
+  },
+} satisfies Config;
+```
+
+</Step>
+
+<Step>
+
+## Create the React Router server handler
+
+Create `server/ssr.ts`:
+
+```typescript title="server/ssr.ts" lineNumbers
+import { createRequestHandler } from "react-router";
+
+export default {
+  fetch: createRequestHandler(
+    () => import("virtual:react-router/server-build"),
+    import.meta.env.MODE,
+  ),
+};
+```
+
+This adapts React Router's generated server build to the Fetch API handler Nitro expects.
+
+</Step>
+
+<Step>
+
+## Configure Vite
+
+Update `vite.config.ts`:
+
+```typescript title="vite.config.ts" lineNumbers
+import { reactRouter } from "@react-router/dev/vite";
+import { nitro } from "nitro/vite";
+import { defineConfig } from "vite";
+import { workflow } from "workflow/vite";
+import reactRouterConfig from "./react-router.config";
+
+export default defineConfig({
+  plugins: [
+    reactRouter(),
+    nitro({
+      serverDir: "./server",
+      output: {
+        dir: reactRouterConfig.buildDirectory,
+        serverDir: `${reactRouterConfig.buildDirectory}/server`,
+        publicDir: `${reactRouterConfig.buildDirectory}/client`,
+      },
+    }),
+    workflow({ dirs: ["workflows"] }),
+  ],
+  environments: {
+    ssr: {
+      build: {
+        rollupOptions: {
+          input: "./server/ssr.ts",
+        },
+      },
+    },
+  },
+});
+```
+
+Keep `dirs: ["workflows"]` so subsequent builds do not scan generated files under `build`. Place `reactRouter()` before `nitro()` in the plugin array.
+
+</Step>
+
+<Step>
+
+## Create a workflow
+
+Create `workflows/greeting.ts`:
+
+```typescript title="workflows/greeting.ts" lineNumbers
+export async function greetingWorkflow(name: string) {
+  "use workflow";
+
+  return greet(name);
+}
+
+async function greet(name: string) {
+  "use step";
+
+  return `Hello, ${name}!`;
+}
+```
+
+</Step>
+
+<Step>
+
+## Start the workflow from a Nitro route
+
+Create `server/routes/api/greeting.post.ts`:
+
+```typescript title="server/routes/api/greeting.post.ts" lineNumbers
+import { defineHandler } from "nitro";
+import { start } from "workflow/api";
+import { greetingWorkflow } from "../../../workflows/greeting";
+
+export default defineHandler(async (event) => {
+  const { name } = (await event.req.json()) as { name: string };
+  const run = await start(greetingWorkflow, [name]);
+
+  return { runId: run.runId };
+});
+```
+
+React Router continues to handle your application routes. Nitro handles this server route at `POST /api/greeting`, as well as Workflow SDK's internal routes.
+
+</Step>
+
+<Step>
+
+## Run the app
+
+Start the development server:
+
+```bash
+pnpm vite dev
+```
+
+Then start a workflow:
+
+```bash
+curl -X POST \
+  -H "content-type: application/json" \
+  -d '{"name":"Workflow"}' \
+  http://localhost:3000/api/greeting
+```
+
+Build and start the production server:
+
+```bash
+pnpm vite build
+node ./build/server/index.mjs
+```
+
+You can inspect local runs with `pnpm workflow web`.
+
+</Step>
+
+</Steps>
+
+## Troubleshooting
+
+### Vite reports an invalid SSR input or `path.replace is not a function`
+
+Set `future.v8_viteEnvironmentApi` to `true` in `react-router.config.ts`.
+
+### React Router pages return 404
+
+Check that the `ssr` environment input points to `./server/ssr.ts`.
+
+### A second build tries to compile files under `build/server`
+
+Use `workflow({ dirs: ["workflows"] })`, remove the existing `build` directory once, and rebuild.
+
+### `vite build` finishes output but does not exit
+
+Use `workflow@5.0.0-beta.33` or later with Nitro v3.