workflow 5.0.0-beta.2 → 5.0.0-beta.20

package/docs/api-reference/workflow-errors/run-not-supported-error.mdx

@@ -0,0 +1,58 @@
+---
+title: RunNotSupportedError
+description: Thrown when a workflow run requires a newer workflow spec version than the installed SDK supports.
+type: reference
+summary: Catch RunNotSupportedError when stored run data requires a newer workflow package version.
+related:
+  - /docs/foundations/versioning
+---
+
+`RunNotSupportedError` is thrown when reading a workflow run whose data was written with a newer workflow spec version than the running SDK supports. This typically means the run was created by a newer version of the `workflow` package — upgrade the package to process it.
+
+```typescript lineNumbers
+import { RunNotSupportedError } from "workflow/errors"
+declare function readRun(runId: string): Promise<unknown>; // @setup
+declare const runId: string; // @setup
+
+try {
+  await readRun(runId);
+} catch (error) {
+  if (RunNotSupportedError.is(error)) { // [!code highlight]
+    console.error(
+      `Run requires spec v${error.runSpecVersion}, world supports v${error.worldSpecVersion}`
+    );
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface RunNotSupportedError {
+  /** The spec version the run's stored data requires. */
+  runSpecVersion: number;
+  /** The spec version the current World supports. */
+  worldSpecVersion: number;
+  /** The error message. */
+  message: string;
+}
+export default RunNotSupportedError;`}
+/>
+
+### Static Methods
+
+#### `RunNotSupportedError.is(value)`
+
+Type-safe check for `RunNotSupportedError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { RunNotSupportedError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (RunNotSupportedError.is(error)) {
+  // error is typed as RunNotSupportedError
+}
+```

package/docs/api-reference/workflow-errors/workflow-error.mdx

@@ -0,0 +1,52 @@
+---
+title: WorkflowError
+description: Base class for all workflow error types.
+type: reference
+summary: All errors thrown by the Workflow SDK extend WorkflowError.
+related:
+  - /docs/foundations/errors-and-retries
+---
+
+`WorkflowError` is the base class that all Workflow SDK error types extend, such as [`WorkflowRunFailedError`](/docs/api-reference/workflow-errors/workflow-run-failed-error) and [`HookNotFoundError`](/docs/api-reference/workflow-errors/hook-not-found-error). It extends `Error` with an optional `cause` and, for some subclasses, a link to the relevant error documentation appended to the message.
+
+```typescript lineNumbers
+import { WorkflowError } from "workflow/errors"
+
+const error = new WorkflowError("something went wrong", {
+  cause: new Error("underlying cause"),
+});
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface WorkflowError {
+  /** The error message. */
+  message: string;
+  /** The underlying cause, when provided. */
+  cause?: unknown;
+}
+export default WorkflowError;`}
+/>
+
+### Static Methods
+
+#### `WorkflowError.is(value)`
+
+Type-safe check for `WorkflowError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+<Callout type="warn">
+  `WorkflowError.is()` matches only direct `WorkflowError` instances — not subclasses, which override the error name it checks. To handle a specific error type, use that subclass's own `.is()` method (e.g. `WorkflowRunFailedError.is(error)`).
+</Callout>
+
+```typescript
+import { WorkflowError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowError.is(error)) {
+  // error is typed as WorkflowError
+}
+```

package/docs/api-reference/workflow-errors/workflow-run-failed-error.mdx

@@ -11,7 +11,7 @@ related:
 
 `WorkflowRunFailedError` is thrown when awaiting `run.returnValue` on a workflow run whose status is `'failed'`. This indicates that the workflow encountered a fatal error during execution and cannot produce a return value.
 
-The `cause` property contains the underlying error with its message, stack trace, and optional error code.
+The `cause` property holds the original thrown value, hydrated through the workflow serialization pipeline so its type identity (e.g. `FatalError`, `RetryableError`, custom `Error` subclasses), `cause` chain, and custom properties are preserved. Because any JavaScript value can be thrown, `cause` is typed as `unknown` — narrow it with `instanceof Error` (or a more specific check) before accessing fields like `message`. The high-level error classification is exposed as the top-level `errorCode` property.
 
 ```typescript lineNumbers
 import { WorkflowRunFailedError } from "workflow/errors"
@@ -21,9 +21,11 @@ try {
   const result = await run.returnValue;
 } catch (error) {
   if (WorkflowRunFailedError.is(error)) { // [!code highlight]
-    console.error(`Run ${error.runId} failed:`, error.cause.message);
-    if (error.cause.code) {
-      console.error("Error code:", error.cause.code);
+    if (error.cause instanceof Error) {
+      console.error(`Run ${error.runId} failed:`, error.cause.message);
+    }
+    if (error.errorCode) {
+      console.error("Error code:", error.errorCode);
     }
   }
 }
@@ -38,8 +40,16 @@ definition={`
 interface WorkflowRunFailedError {
   /** The ID of the failed run. */
   runId: string;
-  /** The underlying error that caused the failure. */
-  cause: Error & { code?: string };
+  /**
+   * The original thrown value from the failed workflow run, hydrated through
+   * the workflow serialization pipeline. Preserves the original type identity
+   * (Error subclasses, FatalError, custom classes with WORKFLOW_SERIALIZE,
+   * etc.) and custom properties. Typed as \`unknown\` because any value can
+   * be thrown — narrow with \`instanceof Error\` before accessing fields.
+   */
+  cause: unknown;
+  /** The high-level error category (e.g. \`USER_ERROR\`, \`RUNTIME_ERROR\`). */
+  errorCode?: string;
   /** The error message. */
   message: string;
 }

package/docs/api-reference/workflow-errors/workflow-run-not-completed-error.mdx

@@ -0,0 +1,58 @@
+---
+title: WorkflowRunNotCompletedError
+description: Thrown when requesting the result of a workflow run that has not completed yet.
+type: reference
+summary: Catch WorkflowRunNotCompletedError when reading the return value of a run that is still pending or running.
+related:
+  - /docs/api-reference/workflow-api/get-run
+---
+
+`WorkflowRunNotCompletedError` is thrown when requesting the result of a workflow run that has not completed yet. The run's current status (for example `pending` or `running`) is available on the error.
+
+[`run.returnValue()`](/docs/api-reference/workflow-api/get-run) handles this error internally — it polls until the run completes — so you will mainly encounter it when building custom polling logic on lower-level APIs.
+
+```typescript lineNumbers
+import { WorkflowRunNotCompletedError } from "workflow/errors"
+declare function readRunResult(runId: string): Promise<unknown>; // @setup
+declare const runId: string; // @setup
+
+try {
+  const result = await readRunResult(runId);
+} catch (error) {
+  if (WorkflowRunNotCompletedError.is(error)) { // [!code highlight]
+    console.log(`Run ${error.runId} is still ${error.status}`);
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface WorkflowRunNotCompletedError {
+  /** The workflow run ID. */
+  runId: string;
+  /** The run's status at the time of the error (e.g. "pending", "running"). */
+  status: string;
+  /** The error message. */
+  message: string;
+}
+export default WorkflowRunNotCompletedError;`}
+/>
+
+### Static Methods
+
+#### `WorkflowRunNotCompletedError.is(value)`
+
+Type-safe check for `WorkflowRunNotCompletedError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { WorkflowRunNotCompletedError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowRunNotCompletedError.is(error)) {
+  // error is typed as WorkflowRunNotCompletedError
+}
+```

package/docs/api-reference/workflow-errors/workflow-runtime-error.mdx

@@ -0,0 +1,58 @@
+---
+title: WorkflowRuntimeError
+description: Thrown when the workflow runtime encounters an execution error, such as serialization failures or timeouts.
+type: reference
+summary: Catch WorkflowRuntimeError for runtime-level failures like unserializable values or workflow timeouts.
+related:
+  - /docs/foundations/serialization
+  - /docs/foundations/errors-and-retries
+---
+
+`WorkflowRuntimeError` is thrown when the workflow runtime encounters an error executing a workflow. Common causes include:
+
+- Values crossing the workflow/step boundary that cannot be serialized
+- Workflow execution timeouts
+- Invalid runtime state, such as misconfigured streams
+
+```typescript lineNumbers
+import { WorkflowRuntimeError } from "workflow/errors"
+declare function runWorkflowOperation(): Promise<void>; // @setup
+
+try {
+  await runWorkflowOperation();
+} catch (error) {
+  if (WorkflowRuntimeError.is(error)) { // [!code highlight]
+    console.error("Workflow runtime error:", error.message);
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface WorkflowRuntimeError {
+  /** The error message. */
+  message: string;
+  /** The underlying cause, when provided. */
+  cause?: unknown;
+}
+export default WorkflowRuntimeError;`}
+/>
+
+### Static Methods
+
+#### `WorkflowRuntimeError.is(value)`
+
+Type-safe check for `WorkflowRuntimeError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { WorkflowRuntimeError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowRuntimeError.is(error)) {
+  // error is typed as WorkflowRuntimeError
+}
+```

package/docs/api-reference/workflow-nest/configure-workflow-controller.mdx

@@ -0,0 +1,33 @@
+---
+title: configureWorkflowController
+description: Point WorkflowController at the generated workflow bundles.
+type: reference
+summary: Configure the directory WorkflowController loads workflow bundles from.
+prerequisites:
+  - /docs/getting-started/nestjs
+---
+
+Configures the output directory that [`WorkflowController`](/docs/api-reference/workflow-nest/workflow-controller) loads the generated workflow bundles (`steps.mjs`, `workflows.mjs`, `webhook.mjs`, `manifest.json`) from.
+
+[`WorkflowModule.forRoot()`](/docs/api-reference/workflow-nest/workflow-module) calls this for you with its resolved `outDir` — call it yourself only when registering `WorkflowController` manually. The controller's route handlers throw if no directory has been configured.
+
+## Usage
+
+```typescript title="src/app.module.ts" lineNumbers
+import { join } from "node:path";
+import { configureWorkflowController } from "workflow/nest"; // [!code highlight]
+
+configureWorkflowController(join(process.cwd(), ".nestjs/workflow")); // [!code highlight]
+```
+
+## API Signature
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `outDir` | `string` | Directory containing the generated workflow bundles. Should match the `outDir` used by the builder (default: `.nestjs/workflow` in the working directory). |
+
+### Returns
+
+Returns `void`.

package/docs/api-reference/workflow-nest/index.mdx

@@ -0,0 +1,31 @@
+---
+title: "workflow/nest"
+description: NestJS integration for workflow bundling and HTTP routing.
+type: overview
+summary: Explore the NestJS integration for workflow bundle building and runtime routing.
+related:
+  - /docs/getting-started/nestjs
+---
+
+NestJS integration for Workflow SDK. The `WorkflowModule` builds the workflow bundles on application startup and registers the controller that serves the workflow runtime routes.
+
+<Callout>
+NestJS integration is experimental and not yet supported for deployment to Vercel. The same exports are also available from the `@workflow/nest` package.
+</Callout>
+
+## Exports
+
+<Cards>
+    <Card title="WorkflowModule" href="/docs/api-reference/workflow-nest/workflow-module">
+        NestJS module that builds workflow bundles on startup and registers the workflow controller
+    </Card>
+    <Card title="NestLocalBuilder" href="/docs/api-reference/workflow-nest/nest-local-builder">
+        Builder that compiles workflow files into step, workflow, and webhook bundles
+    </Card>
+    <Card title="WorkflowController" href="/docs/api-reference/workflow-nest/workflow-controller">
+        Controller that serves the workflow runtime routes under `.well-known/workflow/v1`
+    </Card>
+    <Card title="configureWorkflowController()" href="/docs/api-reference/workflow-nest/configure-workflow-controller">
+        Points `WorkflowController` at the directory containing the generated workflow bundles
+    </Card>
+</Cards>

package/docs/api-reference/workflow-nest/meta.json

@@ -0,0 +1,9 @@
+{
+  "title": "workflow/nest",
+  "pages": [
+    "workflow-module",
+    "nest-local-builder",
+    "workflow-controller",
+    "configure-workflow-controller"
+  ]
+}

package/docs/api-reference/workflow-nest/nest-local-builder.mdx

@@ -0,0 +1,64 @@
+---
+title: NestLocalBuilder
+description: Builder that compiles workflow files into bundles for NestJS apps.
+type: reference
+summary: Use NestLocalBuilder to build workflow bundles programmatically in a NestJS project.
+prerequisites:
+  - /docs/getting-started/nestjs
+---
+
+Builder that scans a NestJS project for workflow files and compiles them into the step, workflow, and webhook bundles plus a manifest. [`WorkflowModule.forRoot()`](/docs/api-reference/workflow-nest/workflow-module) creates and runs one automatically on startup — instantiate it yourself only when you need to build bundles outside the module lifecycle (e.g. a custom build script for production with `skipBuild`).
+
+## Usage
+
+```typescript title="scripts/build-workflows.ts" lineNumbers
+import { NestLocalBuilder } from "workflow/nest"; // [!code highlight]
+
+const builder = new NestLocalBuilder({
+  dirs: ["src"],
+});
+
+await builder.build(); // [!code highlight]
+
+console.log(`Workflow bundles written to ${builder.outDir}`);
+```
+
+## API Signature
+
+### Constructor
+
+`new NestLocalBuilder(options?)` creates a builder for the given options.
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `NestBuilderOptions` | Optional. Configures the workflow build. |
+
+#### NestBuilderOptions
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `workingDir` | `string` | `process.cwd()` | Working directory for the NestJS application. |
+| `dirs` | `string[]` | `['src']` | Directories to scan for workflow files. |
+| `outDir` | `string` | `'.nestjs/workflow'` (relative to `workingDir`) | Output directory for generated workflow bundles. |
+| `watch` | `boolean` | `false` | Enable watch mode for development. |
+| `moduleType` | `'es6' \| 'commonjs'` | `'es6'` | SWC module compilation type. When `'commonjs'`, the builder rewrites externalized imports in the steps bundle to use `require()` via `createRequire`, avoiding ESM/CJS named-export interop issues with SWC's output. |
+| `distDir` | `string` | `'dist'` | Directory where NestJS compiles `.ts` source files to `.js` (relative to `workingDir`). Used when `moduleType` is `'commonjs'` to resolve compiled file paths. Should match the `outDir` in your `tsconfig.json`. |
+| `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. Can also be set via the `WORKFLOW_SOURCEMAP` environment variable. |
+
+### Methods
+
+#### `build()`
+
+Builds the workflow bundles. Writes `steps.mjs`, `workflows.mjs`, `webhook.mjs`, and `manifest.json` to the output directory (plus a `.gitignore` covering the generated files when not deploying to Vercel). Returns `Promise<void>`.
+
+### Properties
+
+#### `outDir`
+
+Read-only getter that returns the output directory for generated workflow bundles — the `outDir` option as passed, or the default `.nestjs/workflow` resolved against `workingDir`.
+
+### Returns
+
+The constructor returns a `NestLocalBuilder` instance.

package/docs/api-reference/workflow-nest/workflow-controller.mdx

@@ -0,0 +1,40 @@
+---
+title: WorkflowController
+description: NestJS controller that serves the workflow runtime routes.
+type: reference
+summary: WorkflowController handles the well-known workflow endpoints in a NestJS app.
+prerequisites:
+  - /docs/getting-started/nestjs
+---
+
+NestJS controller that handles the well-known workflow endpoints under `.well-known/workflow/v1`. It dynamically imports the generated workflow bundles and converts between Express/Fastify requests and the Web API `Request`/`Response` objects the workflow runtime expects. Both the Express and Fastify HTTP adapters are supported.
+
+[`WorkflowModule.forRoot()`](/docs/api-reference/workflow-nest/workflow-module) registers this controller automatically — you only register it yourself if you are not using `WorkflowModule`.
+
+## Usage
+
+When registering the controller manually, call [`configureWorkflowController`](/docs/api-reference/workflow-nest/configure-workflow-controller) first so it can locate the generated bundles; its route handlers throw otherwise.
+
+```typescript title="src/app.module.ts" lineNumbers
+import { join } from "node:path";
+import { Module } from "@nestjs/common";
+import {
+  configureWorkflowController, // [!code highlight]
+  WorkflowController, // [!code highlight]
+} from "workflow/nest";
+
+configureWorkflowController(join(process.cwd(), ".nestjs/workflow")); // [!code highlight]
+
+@Module({
+  controllers: [WorkflowController], // [!code highlight]
+})
+export class AppModule {}
+```
+
+## Routes
+
+| Route | Method | Description |
+| --- | --- | --- |
+| `/.well-known/workflow/v1/flow` | `POST` | Executes workflow and step work items via the combined handler in `workflows.mjs` (step registrations are imported from `steps.mjs` first). |
+| `/.well-known/workflow/v1/webhook/:token` | Any | Forwards webhook requests to the handler in `webhook.mjs`. |
+| `/.well-known/workflow/v1/manifest.json` | `GET` | Serves the workflow manifest. Responds with `404` unless the `WORKFLOW_PUBLIC_MANIFEST=1` environment variable is set. |

package/docs/api-reference/workflow-nest/workflow-module.mdx

@@ -0,0 +1,74 @@
+---
+title: WorkflowModule
+description: NestJS module that builds workflow bundles and registers the workflow controller.
+type: reference
+summary: Import WorkflowModule.forRoot() in your AppModule to enable workflows in a NestJS app.
+prerequisites:
+  - /docs/getting-started/nestjs
+---
+
+NestJS module that provides workflow functionality. It builds the workflow bundles on module initialization (`onModuleInit`) and registers the [`WorkflowController`](/docs/api-reference/workflow-nest/workflow-controller) that serves the workflow runtime routes.
+
+## Usage
+
+Add `WorkflowModule.forRoot()` to the `imports` array of your root module.
+
+```typescript title="src/app.module.ts" lineNumbers
+import { Module } from "@nestjs/common";
+import { WorkflowModule } from "workflow/nest"; // [!code highlight]
+
+@Module({
+  imports: [WorkflowModule.forRoot()], // [!code highlight]
+})
+export class AppModule {}
+```
+
+If your NestJS project compiles to CommonJS via SWC, pass `moduleType` and `distDir` so the builder can rewrite imports in the generated bundles:
+
+```typescript title="src/app.module.ts" lineNumbers
+import { Module } from "@nestjs/common";
+import { WorkflowModule } from "workflow/nest";
+
+@Module({
+  imports: [
+    WorkflowModule.forRoot({
+      moduleType: "commonjs", // [!code highlight]
+      distDir: "dist", // [!code highlight]
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## API Signature
+
+### Static Methods
+
+#### `forRoot(options?)`
+
+Configures the module and returns a NestJS `DynamicModule` registered as `global`. It calls [`configureWorkflowController`](/docs/api-reference/workflow-nest/configure-workflow-controller) with the resolved output directory, and (unless `skipBuild` is set) creates a [`NestLocalBuilder`](/docs/api-reference/workflow-nest/nest-local-builder) that builds the workflow bundles when the module initializes.
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `WorkflowModuleOptions` | Optional. Configures the workflow build. |
+
+#### WorkflowModuleOptions
+
+Extends [`NestBuilderOptions`](/docs/api-reference/workflow-nest/nest-local-builder#nestbuilderoptions) — all builder options are accepted, plus `skipBuild`:
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `skipBuild` | `boolean` | `false` | Skip building workflow bundles on startup. Useful in production when the bundles are pre-built. |
+| `workingDir` | `string` | `process.cwd()` | Working directory for the NestJS application. |
+| `dirs` | `string[]` | `['src']` | Directories to scan for workflow files. |
+| `outDir` | `string` | `'.nestjs/workflow'` (relative to `workingDir`) | Output directory for generated workflow bundles. |
+| `watch` | `boolean` | `false` | Enable watch mode for development. |
+| `moduleType` | `'es6' \| 'commonjs'` | `'es6'` | SWC module compilation type. Set to `'commonjs'` if your NestJS project compiles to CJS via SWC. |
+| `distDir` | `string` | `'dist'` | Directory where NestJS compiles `.ts` source files to `.js` (relative to `workingDir`). Used when `moduleType` is `'commonjs'`. Should match the `outDir` in your `tsconfig.json`. |
+| `sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` (dev) / `false` (prod) | Controls source maps on generated workflow bundles. Defaults to `'inline'` in development and `false` in production. Can also be set via the `WORKFLOW_SOURCEMAP` environment variable. |
+
+### Returns
+
+`forRoot()` returns a `DynamicModule` to include in the `imports` array of your root module.

package/docs/api-reference/workflow-next/with-workflow.mdx

@@ -27,6 +27,15 @@ const workflowConfig = {}
 export default withWorkflow(nextConfig, workflowConfig); // [!code highlight]
 ```
 
+<Callout type="warn">
+If a package in `serverExternalPackages` contains workflow code (`"use step"`,
+`"use workflow"`, or serialization classes), `withWorkflow()` automatically
+removes it from `serverExternalPackages` for the current build and prints a
+warning. Workflow still compiles the package so its directives are transformed.
+Remove that package from `serverExternalPackages` in your
+`next.config` to silence the warning.
+</Callout>
+
 ### Monorepos and Workspace Imports
 
 By default, Next.js detects the correct workspace root automatically. If your Next.js app lives in a subdirectory such as `apps/web` and workspace resolution is not working correctly, you can set `outputFileTracingRoot` as a workaround:
@@ -59,18 +68,40 @@ const nextConfig: NextConfig = {};
 
 export default withWorkflow(nextConfig, {
   workflows: {
-    lazyDiscovery: true,
+    lazyDiscovery: false,
     local: {
       port: 4000,
     },
+    sourcemap: false,
   },
 });
 ```
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `workflows.lazyDiscovery` | `boolean` | `false` | When `true`, defers workflow discovery until files are requested instead of scanning eagerly at startup. Useful for large projects where startup time matters. |
+| `workflows.lazyDiscovery` | `boolean` | `true` | Defers workflow discovery until files are requested instead of scanning eagerly at startup. Set to `false` to force eager discovery (scanning the project up front). Requires a Next.js version that supports deferred entries; older versions fall back to eager discovery automatically. |
 | `workflows.local.port` | `number` | — | Overrides the `PORT` environment variable for local development. Has no effect when deployed to Vercel. |
+| `workflows.sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` (dev) / `false` (prod) | Controls source maps on generated workflow bundles. See [Source maps](#source-maps) below. |
+
+### Source maps
+
+The step bundle and intermediate workflow bundle default to `'inline'` source maps **in development** — so stack traces from step errors and workflow VM errors point at your source files — and to **`false` in production**, so function bundles stay small. The `sourcemap` option lets you change that:
+
+| Value | Behavior |
+| --- | --- |
+| `true` / `'inline'` | Base64-encode the source map and append it to the bundle (default in development). |
+| `'linked'` | Write a separate `.map` file and add a `sourceMappingURL` comment. |
+| `'external'` | Write a separate `.map` file without the comment. |
+| `'both'` | Emit both inline and external source maps. |
+| `false` | Omit source maps entirely. |
+
+In production, source maps are already off by default. Setting `sourcemap: false` explicitly also turns them off in development, and it drops the inline source map from every bundle while skipping the source-map-support runtime shim on the Vercel step function (the same behavior production gets by default) — the main lever for staying under the Vercel 250MB function size limit. The tradeoff is that workflow VM stack traces will reference generated code (e.g. `evalmachine.<anonymous>`) rather than your source files.
+
+<Callout type="info">
+Setting `sourcemap` explicitly affects **all** generated bundles (steps, workflows, webhook). The legacy `WORKFLOW_EMIT_SOURCEMAPS_FOR_DEBUGGING=1` environment variable is narrower — it only toggles source maps on the final workflow wrapper and webhook bundle (which default to off). It continues to work, but new code should use the `sourcemap` option or the `WORKFLOW_SOURCEMAP` environment variable instead.
+</Callout>
+
+The option can also be set via the `WORKFLOW_SOURCEMAP` environment variable, which accepts the same values plus `'0'` / `'1'` as aliases for `false` / `true`. Precedence is: explicit config > `WORKFLOW_SOURCEMAP` > the environment-aware default (`'inline'` in development, `false` in production). Development is detected from `next dev` / `NODE_ENV=development`, so the config option and the env var both let you force either behavior in either environment.
 
 <Callout type="info">
 The `workflows.local` options only affect local development. When deployed to Vercel, the runtime ignores `local` settings and uses the Vercel world automatically.
@@ -78,6 +109,7 @@ The `workflows.local` options only affect local development. When deployed to Ve
 
 ## Exporting a Function
 
+
 If you are exporting a function in your `next.config` you will need to ensure you call the function returned from `withWorkflow`.
 
 ```typescript title="next.config.ts" lineNumbers

package/docs/api-reference/workflow-nitro/index.mdx

@@ -0,0 +1,59 @@
+---
+title: "workflow/nitro"
+description: Nitro module for automatic workflow bundling and route registration.
+type: overview
+summary: Explore the Nitro module that enables workflow directive transformation in Nitro apps.
+related:
+  - /docs/getting-started/nitro
+---
+
+Nitro integration for Workflow SDK. The `workflow/nitro` entry point's default export is a [Nitro module](https://v3.nitro.build/guide/modules) — it has no callable API. You enable it by adding it to the `modules` array of your Nitro config and configure it via the `workflow` key.
+
+## Usage
+
+```typescript title="nitro.config.ts" lineNumbers
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  serverDir: "./server",
+  modules: ["workflow/nitro"], // [!code highlight]
+});
+```
+
+When enabled, the module:
+
+- Transforms `"use workflow"` and `"use step"` directives during bundling.
+- Builds the workflow, step, and webhook bundles, and rebuilds them on file changes in development.
+- Registers the workflow runtime routes under `/.well-known/workflow/v1/`.
+- Serves a redirect to the local observability dashboard at `/_workflow` in development.
+- Configures Vercel function rules (queue triggers and `maxDuration`) for the workflow routes when deploying to Vercel.
+
+## Module Options
+
+Options are read from the `workflow` key of your Nitro config. The option type is exported as `ModuleOptions`:
+
+```typescript title="nitro.config.ts" lineNumbers
+import { defineConfig } from "nitro";
+import type { ModuleOptions } from "workflow/nitro"; // [!code highlight]
+
+const workflow: ModuleOptions = {
+  runtime: "nodejs22.x",
+  sourcemap: "inline",
+};
+
+export default defineConfig({
+  modules: ["workflow/nitro"],
+  workflow, // [!code highlight]
+});
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dirs` | `string[]` | — | Directories to scan for workflows and steps. By default, the `workflows/` directory is scanned from the project root and all layer source directories. |
+| `typescriptPlugin` | `boolean` | `false` | Adds the `workflow` TypeScript plugin to the generated `tsconfig.json` for IDE IntelliSense. |
+| `runtime` | `string` | — | Node.js runtime version for Vercel Functions (e.g. `'nodejs22.x'`, `'nodejs24.x'`). Only applies when deploying to Vercel. |
+| `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. |
+
+## Vite-based Nitro
+
+If you use Nitro through its Vite plugin (`nitro/vite`) instead of a standalone `nitro.config.ts`, use the [`workflow/vite`](/docs/api-reference/workflow-vite) entry point, which wraps this module as a Vite plugin and accepts the same `ModuleOptions`.