workflow 4.3.1 → 4.5.0

package/docs/v4/errors/runtime-decryption-failed.mdx

@@ -0,0 +1,77 @@
+---
+title: runtime-decryption-failed
+description: The SDK's built-in AES-GCM encryption layer failed to encrypt or decrypt a workflow payload.
+type: troubleshooting
+summary: Resolve runtime decryption failures caused by ciphertext corruption, key mismatch, or malformed envelopes.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/foundations/errors-and-retries
+---
+
+This error occurs when the Workflow SDK's built-in AES-GCM encryption layer fails while encrypting or decrypting a workflow payload. The SDK encrypts step inputs, step outputs, hook payloads, and other event-log data with a per-run AES-256 key whenever encryption is configured for the deployment.
+
+This is an **internal SDK failure** — your workflow code never invokes the encryption primitives directly. When this surfaces, it means the ciphertext, nonce, or auth tag the SDK tried to verify is not the bytes that were originally produced. The run is failed with the `RUNTIME_ERROR` classification.
+
+## Error Message
+
+```
+AES-256-GCM decryption failed: The operation failed for an operation-specific reason
+```
+
+The underlying cause is a native Web Crypto [`OperationError`](https://developer.mozilla.org/en-US/docs/Web/API/DOMException#operationerror) — most commonly raised by `AESCipherJob.onDone` in Node's `node:internal/crypto/util` module when the GCM authentication tag does not verify.
+
+The thrown `RuntimeDecryptionError` carries a small `context` object with diagnostic fields to help triangulate the source:
+
+- `operation` — `'encrypt'` or `'decrypt'`
+- `byteLength` — total byte length of the payload at the failure site
+- `formatPrefix` — the first 4 bytes of the input (`'encr'` for a well-formed encrypted envelope, otherwise a hex dump)
+
+## Why This Happens
+
+Common causes, in rough order of likelihood:
+
+1. **Ciphertext mutation or truncation in transit.** The encrypted payload reached the SDK with bytes that differ from what storage holds. Possible sources include a truncated HTTP response from a workflow-server ref endpoint, an edge-cache miss returning a partial 200, or a proxy drop during streaming. A truncated body whose first 4 bytes happen to still spell `encr` produces the exact "auth tag mismatch" symptom.
+2. **Key resolution mismatch.** The key used to decrypt is not the key that was used to encrypt — e.g. the run's `deploymentId` was not threaded through key resolution and the SDK fell back to the wrong deployment's key material.
+3. **Malformed encrypted envelope.** The envelope is too short to contain the GCM nonce (12 bytes) and auth tag (16 bytes), so decryption is rejected before it begins.
+
+## What To Do
+
+This error indicates an SDK or infrastructure problem — not a bug in your workflow code. Your workflow code does not need to change.
+
+### 1. Upgrade to the latest `workflow` package
+
+The underlying issue may have already been identified and fixed:
+
+```bash
+npm install workflow@latest
+```
+
+### 2. Retry the failed run
+
+Since this is a fatal error, the run is automatically marked as `failed`. You can re-run it using the **Re-run** button in the Workflow Dashboard.
+
+### 3. Report the issue
+
+If the error persists after upgrading, please [open an issue on GitHub](https://github.com/vercel/workflow/issues/new) so we can investigate. Include:
+
+- The version of the `workflow` package you are using
+- The run ID(s) of the affected workflow run(s)
+- The full error message, including the `context` fields (`operation`, `byteLength`, `formatPrefix`)
+- Whether the affected workflows make heavy use of large step inputs/outputs (which may indicate the failure is on the lazy-loaded ref read path)
+
+## This Error Cannot Be Caught
+
+Like other `WorkflowRuntimeError` subclasses, a runtime decryption failure is **not catchable** inside your workflow function. The runtime cannot safely continue executing user code when an event-log payload can't be verified, so the entire run fails immediately and is marked as `failed`.
+
+To handle this programmatically from outside the workflow, check the run status:
+
+```typescript lineNumbers
+import { getRun } from "workflow/api";
+
+const run = getRun("wrun_abc123");
+const status = await run.status;
+if (status === "failed") {
+  console.error("Run failed");
+}
+```

package/docs/v4/errors/step-executed-multiple-times.mdx

@@ -0,0 +1,23 @@
+---
+title: Step executed multiple times
+description: A step ran more than once because its function invocation crashed before it could report a result.
+type: troubleshooting
+summary: Diagnose duplicate step_started events caused by function timeouts, OOMs, or network issues.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability
+  - /docs/foundations/errors-and-retries
+---
+
+There may be cases where you see multiple `step_started` events for the same step in a workflow run. This happens if the function invocation executing the step crashes unexpectedly, and the step can not report the error. The step will be re-tried according to your retry policy in this case, but no error will be visible in the [Observability UI](/docs/observability).
+
+## Common Causes
+
+- **Function timeouts**: if your step code runs longer than the configured maximum function duration, it will be killed. Compare the gap between the `step_started` events to your configured function duration to be sure.
+- **Out of memory (OOM)**: if your step code loads enough data into memory, especially if the step is invoked concurrently, the function invocation might run out of memory. You can see your function's peak memory use by going to the [Observability Query page](https://vercel.com/docs/observability) and showing the **Function Invocation Peak Memory** metric, then filtering down the **Route** to `/.well-known/workflow` endpoints.
+- **Network issues**: persistent firewall, network stability, and related issues might prevent your function from reporting results or errors. This should be temporary.
+
+## Getting Help
+
+If you consistently see multiple `step_started` events and have ruled out function timeouts, OOMs, and firewall issues, please [contact support](https://vercel.com/help).

package/docs/v5/api-reference/workflow-astro/index.mdx

@@ -0,0 +1,18 @@
+---
+title: "workflow/astro"
+description: Astro integration for automatic workflow bundling and route registration.
+type: overview
+summary: Explore the Astro integration for automatic workflow bundling and runtime support.
+related:
+  - /docs/getting-started/astro
+---
+
+Astro integration for Workflow SDK that transforms workflow code and builds the workflow bundles.
+
+## Functions
+
+<Cards>
+    <Card title="workflow()" href="/docs/api-reference/workflow-astro/workflow">
+        Astro integration that transforms workflow code (`"use step"`/`"use workflow"` directives)
+    </Card>
+</Cards>

package/docs/v5/api-reference/workflow-astro/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "workflow/astro",
+  "pages": ["workflow"]
+}

package/docs/v5/api-reference/workflow-astro/workflow.mdx

@@ -0,0 +1,45 @@
+---
+title: workflow
+description: Configure Astro to transform workflow directives.
+type: reference
+summary: Add the workflow integration to your Astro config to enable workflow directive transformation.
+prerequisites:
+  - /docs/getting-started/astro
+---
+
+Returns an Astro integration that transforms workflow code (`"use step"`/`"use workflow"` directives) and builds the workflow bundles.
+
+## Usage
+
+To enable `"use step"` and `"use workflow"` directives while developing locally or deploying to production, add `workflow()` to the `integrations` array of your Astro config.
+
+```typescript title="astro.config.mjs" lineNumbers
+// @ts-check
+import { defineConfig } from "astro/config";
+import { workflow } from "workflow/astro"; // [!code highlight]
+
+// https://astro.build/config
+export default defineConfig({
+  integrations: [workflow()], // [!code highlight]
+});
+```
+
+The integration registers the workflow Vite transform plugins during `astro:config:setup` and builds the workflow bundles — locally during config setup, or via the Vercel builder after `astro:build:done` when deploying to Vercel.
+
+## API Signature
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `WorkflowPluginOptions` | Optional. Configures the workflow build. |
+
+#### WorkflowPluginOptions
+
+| 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. |
+
+### Returns
+
+Returns an `AstroIntegration` object to include in the `integrations` array of your Astro config.

package/docs/v5/api-reference/workflow-errors/hook-conflict-error.mdx

@@ -0,0 +1,60 @@
+---
+title: HookConflictError
+description: Thrown when creating a hook with a token that is already in use by another workflow run.
+type: reference
+summary: Catch HookConflictError when a hook token is already claimed by another active workflow run.
+related:
+  - /docs/api-reference/workflow/create-hook
+  - /docs/foundations/hooks
+  - /docs/errors/hook-conflict
+---
+
+`HookConflictError` is thrown when creating a hook with a token that is already in use by another active workflow run. Hook tokens must be unique across all running workflows — see the [hook-conflict](/docs/errors/hook-conflict) error guide for resolution strategies.
+
+```typescript lineNumbers
+import { HookConflictError } from "workflow/errors"
+declare function startApprovalWorkflow(token: string): Promise<void>; // @setup
+declare const token: string; // @setup
+
+try {
+  await startApprovalWorkflow(token);
+} catch (error) {
+  if (HookConflictError.is(error)) { // [!code highlight]
+    console.error(
+      `Token "${error.token}" already in use by run ${error.conflictingRunId}`
+    );
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface HookConflictError {
+  /** The hook token that conflicted. */
+  token: string;
+  /** The run ID of the workflow currently holding the token, when known. */
+  conflictingRunId?: string;
+  /** The error message. */
+  message: string;
+}
+export default HookConflictError;`}
+/>
+
+### Static Methods
+
+#### `HookConflictError.is(value)`
+
+Type-safe check for `HookConflictError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { HookConflictError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (HookConflictError.is(error)) {
+  // error is typed as HookConflictError
+}
+```

package/docs/v5/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/v5/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/v5/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/v5/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/v5/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/v5/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/v5/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/v5/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'` | Controls source maps on generated workflow bundles. Accepts the same values as esbuild's `sourcemap` option. 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/v5/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. |