workflow 5.0.0-beta.9 → 5.0.1

package/docs/getting-started/nestjs.mdx

@@ -9,10 +9,15 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
-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.
+<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`."
+/>
+
+Set up your first durable workflow in a NestJS app and learn the core Workflow SDK concepts.
 
 <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>
 
 ---
@@ -20,7 +25,7 @@ NestJS integration is experimental and not yet supported for deployment to Verce
 <Steps>
 
 <Step>
-## Create Your NestJS Project
+## Create your NestJS project
 
 Start by creating a new NestJS project using the NestJS CLI.
 
@@ -41,7 +46,7 @@ cd my-workflow-app
 npm i workflow @workflow/nest
 ```
 
-### Choose Your Module Format
+### Choose your module format
 
 NestJS projects using `@workflow/nest` can compile as either ESM or CommonJS. Choose the setup that matches your SWC output instead of assuming ESM is required.
 
@@ -107,7 +112,7 @@ Ensure your `nest-cli.json` has SWC as the builder:
 }
 ```
 
-### Initialize SWC Configuration
+### Initialize SWC configuration
 
 Run the init command to generate the SWC configuration:
 
@@ -115,7 +120,7 @@ Run the init command to generate the SWC configuration:
 npx @workflow/nest init
 ```
 
-This creates a `.swcrc` file configured with the Workflow SWC plugin for client-mode transformations.
+This creates a `.swcrc` file configured with the Workflow SWC plugin for step-mode transformations.
 
 <Callout>
 Add `.swcrc` to your `.gitignore` as it contains machine-specific absolute paths that shouldn't be committed.
@@ -138,10 +143,10 @@ Add scripts to regenerate the SWC configuration before builds:
 <Accordion type="single" collapsible>
   <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
     <AccordionTrigger className="[&_p]:my-0 text-lg [&_p]:text-foreground">
-      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
 {
@@ -203,7 +208,7 @@ The `WorkflowModule` handles workflow bundle building and provides HTTP routing
 
 <Step>
 
-## Create Your First Workflow
+## Create your first workflow
 
 Create a new file for our first workflow in the `src/workflows` directory:
 
@@ -236,14 +241,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";
@@ -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.
 
@@ -297,7 +302,7 @@ Taking a look at this code:
 
 <Step>
 
-## Create Your Controller
+## Create your controller
 
 To invoke your new workflow, update your controller with a new endpoint:
 
@@ -357,11 +362,67 @@ 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);
+}
+```
+
+No module change is needed for the in-process build: `skipBuild` defaults to `true` when the
+`VERCEL` environment variable is set, because the Build Output already contains the bundles and
+the deployed filesystem is read-only.
+
+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>
 
 ---
 
-## Configuration Options
+## Configuration options
 
 The `WorkflowModule.forRoot()` method accepts optional configuration:
 
@@ -375,7 +436,9 @@ WorkflowModule.forRoot({
   // Output directory for generated bundles (default: '.nestjs/workflow')
   outDir: '.nestjs/workflow',
 
-  // Skip building in production when bundles are pre-built
+  // Skip building when bundles are pre-built with `workflow-nest build`
+  // (default: true when VERCEL is set, false otherwise). Startup fails if the
+  // bundles are missing.
   skipBuild: false,
 
   // SWC module type: 'es6' (default) or 'commonjs'
@@ -387,24 +450,203 @@ WorkflowModule.forRoot({
   // Should match the outDir in your tsconfig.json
   distDir: 'dist',
 
-  // Source maps on generated workflow bundles (default: 'inline').
+  // 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
+  // function bundles (useful for staying under the Vercel 250 MB 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',
+
+  // Route prefix the workflow endpoints are served under. Leave unset to adopt
+  // app.setGlobalPrefix() automatically; set it when a reverse proxy mounts the
+  // app on a sub-path NestJS does not know about. See "Global prefixes" below.
+  basePath: '/api',
+
+  // Start the target World's background workers with the app and close them on
+  // shutdown. Self-hosted Worlds (for example @workflow/world-postgres) need
+  // this or runs are created and never picked up. Leave off on Vercel.
+  manageWorldLifecycle: false,
+
+  // Load the generated bundles during startup instead of on the first request
+  // (default: true, or false when VERCEL is set because dedicated functions
+  // serve the bundles there).
+  preloadBundles: true,
+});
+```
+
+Options can also come from other providers with `forRootAsync`:
+
+{/*@skip-typecheck - Configuration snippet, imports shown above*/}
+
+```typescript
+WorkflowModule.forRootAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    basePath: config.get('API_PREFIX'),
+  }),
 });
 ```
 
+---
+
+## Global prefixes and sub-paths
+
+`app.setGlobalPrefix()` moves the workflow routes. The SDK has to generate its
+queue callback and webhook URLs under the same prefix, or every delivery 404s and
+runs stay `pending`.
+
+`WorkflowModule` reads the global prefix during startup and adopts it, so this
+works with no configuration:
+
+{/*@skip-typecheck - Bootstrap snippet*/}
+
+```typescript
+const app = await NestFactory.create(AppModule);
+app.setGlobalPrefix('api'); // workflow URLs become /api/.well-known/workflow/v1/...
+await app.listen(3000);
+```
+
+Set `basePath` explicitly when the prefix is applied outside NestJS, for example
+by a reverse proxy that strips it before the request reaches your app. An
+explicit `basePath` wins over the global prefix, and a disagreement between the
+two is logged at startup.
+
+For Vercel, pass the same value to the build so the deployed queue-consumer
+function generates matching URLs:
+
+```bash
+workflow-nest build --vercel --base-path /api
+```
+
+<Callout type="warn">
+`app.enableVersioning()` moves the workflow routes the same way, and is not
+handled automatically. Exclude the workflow controller from versioning, or mount
+it where the SDK expects it.
+</Callout>
+
+---
+
+## Raw request bodies
+
+The workflow routes are a byte pipe. A webhook that verifies a signature over its
+raw body (Stripe, GitHub, Shopify, Slack) only works if the bytes the sender
+signed reach the workflow unchanged, and a body parser that has already turned
+the request into an object destroys them.
+
+Create the app with `rawBody` so the original bytes stay available:
+
+{/*@skip-typecheck - Bootstrap snippet*/}
+
+```typescript
+const app = await NestFactory.create(AppModule, { rawBody: true });
+```
+
+Without it, `@workflow/nest` falls back to re-serializing the parsed body with
+`JSON.stringify` and logs a warning once. That changes whitespace and key order,
+so signature verification fails.
+
+Content types no body parser claims (XML, `application/x-www-form-urlencoded`
+without the parser registered, custom media types) are read straight from the
+request stream and need no configuration.
+
+<Callout type="info">
+On Vercel the webhook route is served by its own function rather than by your
+NestJS app, so this only affects self-hosted deployments.
+</Callout>
+
+---
+
+## NestJS dependency injection is not available in workflows and steps
+
+Workflows and steps do not run inside your NestJS application. They are compiled
+into separate bundles, so **the Nest injector, your providers, and anything
+built on the request context are out of reach from `"use workflow"` and
+`"use step"` code.**
+
+Concretely, none of these work inside a step:
+
+- injecting a provider, or resolving one with `app.get(MyService)`
+- `@Injectable()` classes reached through a module-level reference to the app
+- request-scoped providers, and `AsyncLocalStorage` context such as `nestjs-cls`
+- guards, interceptors, pipes, and filters
+- the Nest `Logger`
+
+Two mechanics cause this, and neither has a workaround:
+
+1. A step's bundle gets **its own copy** of any application file it imports.
+   Module-level state is therefore duplicated, and a class imported into a step
+   is a different class object from the one your module registered. Nest uses the
+   class itself as the injection token, so `app.get(MyService)` from a step
+   raises `UnknownElementException` even when it can reach the app.
+2. On Vercel, workflows and steps run in the queue-consumer function, a separate
+   function from the one serving your NestJS app. There is no shared process to
+   reach into.
+
+Write steps as plain functions over their arguments, and keep the wiring in your
+controllers and providers:
+
+{/*@skip-typecheck - Illustrates the pattern, not a complete app*/}
+
+```typescript
+// A step takes what it needs as arguments and builds its own clients.
+async function chargeCustomer(customerId: string, cents: number) {
+  'use step';
+  const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+  return await stripe.charges.create({ customer: customerId, amount: cents });
+}
+
+// The controller stays a normal Nest controller with normal DI.
+@Controller('billing')
+export class BillingController {
+  constructor(private readonly customers: CustomerService) {}
+
+  @Post('charge')
+  async charge(@Body() body: { id: string }) {
+    const customer = await this.customers.find(body.id);
+    // Pass plain, serializable values into the workflow.
+    await start(billingWorkflow, [customer.id, customer.planCents]);
+    return { started: true };
+  }
+}
+```
+
+Configuration a step needs should come from the environment rather than
+`ConfigService`, and shared logic should live in plain modules that a step can
+import without pulling in `@nestjs/common`.
+
+<Callout type="info">
+Importing a file that uses `@nestjs/common` into a step is supported and builds
+correctly, it simply gives you a class with no injected dependencies. Prefer
+plain functions so the intent is clear.
+</Callout>
+
+---
+
+## Production checklist
+
+- Run `workflow-nest build` in your build step and set `skipBuild: true`, or
+  leave `skipBuild` unset so the bundles are built during startup. With
+  `skipBuild` set and no bundles present, startup fails with an explicit error
+  rather than serving broken workflow routes.
+- Create the app with `{ rawBody: true }` if you receive signed webhooks.
+- Set `basePath` (or rely on the adopted global prefix) so generated URLs match
+  the routes NestJS serves.
+- Set `manageWorldLifecycle: true` for a self-hosted World, and call
+  `app.enableShutdownHooks()` so the World is closed on a signal.
+- `skipBuild` defaults to `true` when the `VERCEL` environment variable is set,
+  so no Vercel-specific branch is needed in your module configuration.
+
 ## Troubleshooting
 
 ### `start()` says it received an invalid workflow function
 
 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:
@@ -413,7 +655,8 @@ Check both of these first:
 2. Your NestJS app imports and registers the `WorkflowModule`.
 
 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/next.mdx

@@ -7,13 +7,17 @@ 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>
-## Create Your Next.js Project
+## Create your Next.js project
 
 Start by creating a new Next.js project. This command will create a new directory named `my-workflow-app` and set up a Next.js project inside it.
 
@@ -85,7 +89,7 @@ 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.
 
-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`.
+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 issue can be hard to spot in Next.js 16, where `proxy.ts` replaced `middleware.ts`.
 
 Add `.well-known/workflow/*` to your matcher exclusion list:
 
@@ -117,7 +121,7 @@ This ensures that internal Workflow paths are not intercepted by your middleware
 
 <Step>
 
-## Create Your First Workflow
+## Create your first workflow
 
 Create a new file for our first workflow:
 
@@ -140,14 +144,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. 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
+## 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"
@@ -188,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.
 
@@ -200,7 +204,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 need to add your workflow to a `POST` API Route Handler, `app/api/signup/route.ts`, with the following code:
 
@@ -272,12 +276,12 @@ Check the [Deploying](/docs/deploying) section to learn how your workflows can b
 
 If you see this error when upgrading to Next.js 16.1 or later:
 
-```
+```text
 Build error occurred
 Error: Cannot find module 'next/dist/lib/server-external-packages.json'
 ```
 
-Upgrade to `workflow@4.0.1-beta.26` or later:
+Upgrade `workflow` to the latest release:
 
 ```package-install
 workflow@latest
@@ -311,8 +315,8 @@ 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.
+```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:
@@ -322,7 +326,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/nitro.mdx

@@ -1,6 +1,6 @@
 ---
 title: Nitro
-description: This guide will walk through setting up your first workflow in a Nitro v3 project. 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 Nitro v3 project.
 type: guide
 summary: Set up Workflow SDK in a Nitro app.
 prerequisites:
@@ -9,12 +9,16 @@ 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>
-## Create Your Nitro Project
+## Create your Nitro project
 
-Start by creating a new [Nitro v3](https://v3.nitro.build/) project. This command will create a new directory named `nitro-app` and setup a Nitro project inside it.
+Create a [Nitro v3](https://v3.nitro.build/) project in a new directory named `nitro-app`:
 
 ```bash
 npx create-nitro-app
@@ -34,7 +38,7 @@ npm i workflow
 
 ### Configure Nitro
 
-Add `workflow/nitro` module to your `nitro.config.ts` This enables usage of the `"use workflow"` and `"use step"` directives.
+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";
@@ -66,15 +70,15 @@ export default defineConfig({
 | --- | --- | --- | --- |
 | `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'` | 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="[&_p]:my-0 text-lg [&_p]:text-foreground">
-      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
 {
@@ -98,7 +102,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:
 
@@ -120,14 +124,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";
@@ -168,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.
 
@@ -181,7 +185,7 @@ Taking a look at this code:
 
 <Step>
 
-## Create Your Route Handler
+## 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:
 
@@ -200,7 +204,7 @@ export default defineEventHandler(async ({ req }) => {
 });
 ```
 
-This Route Handler creates a `POST` request endpoint at `/api/signup` that will trigger your workflow.
+This route handler creates a `POST` request endpoint at `/api/signup` that triggers your workflow.
 
 <Callout>
   Workflows can be triggered from API routes or any server-side
@@ -244,7 +248,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 />
 
@@ -256,8 +260,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:
@@ -267,7 +271,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.