workflow 5.0.0-beta.5 → 5.0.0-beta.51

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` or later with Nitro v3.

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

@@ -0,0 +1,232 @@
+---
+title: React Router v8
+description: Add durable workflows to a React Router v8 framework-mode app using Nitro v3.
+type: guide
+summary: Configure React Router v8, Nitro v3, and Workflow SDK in one Vite build.
+prerequisites:
+  - /docs/getting-started/react-router
+related:
+  - /docs/getting-started/nitro
+  - /docs/foundations/workflows-and-steps
+---
+
+This guide starts with an existing React Router v8 framework-mode app.
+
+<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>
+
+## Use a shared build directory
+
+Set an explicit build directory in your React Router config:
+
+```typescript title="react-router.config.ts" lineNumbers
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  ssr: true,
+  buildDirectory: "build", // [!code highlight]
+} satisfies Config;
+```
+
+React Router will place browser assets in `build/client`. Nitro will place the runnable server in `build/server`.
+
+</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
+
+### 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` or later with Nitro v3.

package/docs/getting-started/sveltekit.mdx

@@ -1,6 +1,6 @@
 ---
 title: SvelteKit
-description: This guide will walk through setting up your first workflow in a SvelteKit app. Along the way, you'll learn more about the concepts that are fundamental to using the Workflow SDK in your own projects.
+description: Set up your first durable workflow in a SvelteKit app.
 type: guide
 summary: Set up Workflow SDK in a SvelteKit app.
 prerequisites:
@@ -9,12 +9,16 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
+<CopyPrompt
+  text="In this SvelteKit app, run `npm i workflow`. In `vite.config.ts`, import `workflowPlugin` from `workflow/sveltekit` and add it to `plugins` with `sveltekit()`. Add the TypeScript plugin `{ &quot;name&quot;: &quot;workflow&quot; }` to `tsconfig.json` if TypeScript is used. 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 `src/routes/api/signup/+server.ts` with a POST `RequestHandler` that reads `{ email }`, calls `start(handleUserSignup, [email])` from `workflow/api`, and returns `json({ message: &quot;User signup workflow started&quot; })`. Run `npm run dev`, call `curl -X POST --json '{&quot;email&quot;:&quot;hello@example.com&quot;}' http://localhost:5173/api/signup`, then inspect with `npx workflow web` or `npx workflow inspect runs`."
+/>
+
 <Steps>
 
 <Step>
-## Create Your SvelteKit Project
+## Create your SvelteKit project
 
-Start by creating a new SvelteKit project. This command will create a new directory named `my-workflow-app` with a minimal setup and setup a SvelteKit project inside it.
+Create a minimal SvelteKit project in a new directory named `my-workflow-app`:
 
 ```bash
 npx sv create my-workflow-app --template=minimal --types=ts --no-add-ons
@@ -50,16 +54,16 @@ export default defineConfig({
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` | Controls source maps on generated workflow bundles. Accepts the same values as esbuild's `sourcemap` option. 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` | `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. |
 
 <Accordion type="single" collapsible>
   <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
     <AccordionTrigger className="text-sm">
-      ### Setup IntelliSense for TypeScript (Optional)
+      ### Set up IntelliSense for TypeScript (optional)
     </AccordionTrigger>
     <AccordionContent className="[&_p]:my-2">
 
-To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json`:
+To enable helpful hints in your IDE, set up the workflow plugin in `tsconfig.json`:
 
 ```json title="tsconfig.json" lineNumbers
 {
@@ -82,7 +86,7 @@ To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json
 
 <Step>
 
-## Create Your First Workflow
+## Create your first workflow
 
 Create a new file for our first workflow:
 
@@ -105,14 +109,14 @@ export async function handleUserSignup(email: string) {
 
 ```
 
-We'll fill in those functions next, but let's take a look at this code:
+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
+## Create your workflow steps
 
-Let's now define those missing functions.
+Define the missing functions.
 
 ```typescript title="workflows/user-signup.ts" lineNumbers
 import { FatalError } from "workflow"
@@ -153,7 +157,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.
 
@@ -165,7 +169,7 @@ We'll dive deeper into workflows, steps, and other ways to suspend or handle eve
 
 <Step>
 
-## Create Your Route Handler
+## Create your route handler
 
 To invoke your new workflow, we'll have to add your workflow to a `POST` API route handler, `src/routes/api/signup/+server.ts` with the following code:
 
@@ -228,7 +232,7 @@ npx workflow inspect runs
 
 ## Deploying to production
 
-Workflow SDK apps currently work best when deployed to [Vercel](https://vercel.com/home) and needs no special configuration.
+Workflow SDK apps currently work best when deployed to [Vercel](https://vercel.com/home) and need no special configuration.
 
 <FluidComputeCallout />
 
@@ -240,8 +244,8 @@ 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.
+```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:
@@ -251,7 +255,7 @@ Check both of these first:
 
 See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.
 
-## Next Steps
+## Next steps
 
 * Learn more about the [Foundations](/docs/foundations).
 * Check [Errors](/docs/errors) if you encounter issues.

package/docs/getting-started/tanstack-start.mdx

@@ -9,14 +9,18 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
-This guide will walk through setting up your first workflow in a TanStack Start app. Along the way, you'll learn more about the concepts that are fundamental to using the Workflow SDK in your own projects.
+<CopyPrompt
+  text="In this TanStack Start app, run `npm i workflow`. In `vite.config.ts`, import `workflow` from `workflow/vite` and add `workflow()` first in the existing `plugins` array before `tanstackStart()`, `nitro()`, or other plugins. Add `{ &quot;name&quot;: &quot;workflow&quot; }` to `compilerOptions.plugins` in `tsconfig.json` if TypeScript is used. Create `src/workflows/user-signup.ts` with `handleUserSignup(email)`, `&quot;use workflow&quot;`, `sleep`, and `&quot;use step&quot;` helpers. Add `src/routes/api/signup.ts` using `createFileRoute(&quot;/api/signup&quot;)`, a POST server handler, `start` from `workflow/api`, and `json` from `@tanstack/react-start`. 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`."
+/>
+
+Set up your first durable workflow in a TanStack Start app and learn the core Workflow SDK concepts.
 
 ---
 
 <Steps>
 
 <Step>
-## Create Your TanStack Start Project
+## Create your TanStack Start project
 
 Start by creating a new TanStack Start project:
 
@@ -38,7 +42,7 @@ npm i workflow
 
 ### Configure TanStack Start
 
-TanStack Start runs on Vite, so the Workflow SDK is wired in via the same `workflow/vite` plugin. Add `workflow()` to the existing `plugins` array in your Vite config — list it first so the `"use workflow"` and `"use step"` transforms run before any other plugin processes the file.
+TanStack Start runs on Vite, so the Workflow SDK is wired in via the same `workflow/vite` plugin. Add `workflow()` to the existing `plugins` array in your Vite config. List it first so the `"use workflow"` and `"use step"` transforms run before any other plugin processes the file.
 
 ```typescript title="vite.config.ts" lineNumbers
 import { defineConfig } from "vite";
@@ -56,11 +60,11 @@ export default defineConfig({
 <Accordion type="single" collapsible>
   <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
     <AccordionTrigger className="text-sm">
-      ### Setup IntelliSense for TypeScript (Optional)
+      ### Set up IntelliSense for TypeScript (optional)
     </AccordionTrigger>
     <AccordionContent className="[&_p]:my-2">
 
-To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json`:
+To enable helpful hints in your IDE, set up the workflow plugin in `tsconfig.json`:
 
 ```json title="tsconfig.json" lineNumbers
 {
@@ -83,7 +87,7 @@ To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json
 
 <Step>
 
-## Create Your First Workflow
+## Create your first workflow
 
 Create a new file for our first workflow:
 
@@ -103,14 +107,14 @@ export async function handleUserSignup(email: string) {
 }
 ```
 
-We'll fill in those functions next, but let's take a look at this code:
+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
+## Create your workflow steps
 
-Let's now define those missing functions.
+Define the missing functions.
 
 ```typescript title="src/workflows/user-signup.ts" lineNumbers
 import { FatalError } from "workflow"
@@ -151,7 +155,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.
 
@@ -163,7 +167,7 @@ We'll dive deeper into workflows, steps, and other ways to suspend or handle eve
 
 <Step>
 
-## Create Your Route Handler
+## Create your route handler
 
 To invoke your new workflow, add a server handler at `src/routes/api/signup.ts`:
 
@@ -228,13 +232,13 @@ npx workflow inspect runs
 
 ## Deploying to production
 
-Workflow SDK apps currently work best when deployed to [Vercel](https://vercel.com/home) and needs no special configuration.
+Workflow SDK apps currently work best when deployed to [Vercel](https://vercel.com/home) and need no special configuration.
 
 <FluidComputeCallout />
 
 Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
-## Next Steps
+## Next steps
 
 * Learn more about the [Foundations](/docs/foundations).
 * Check [Errors](/docs/errors) if you encounter issues.