workflow 5.0.0-beta.9 → 5.0.1

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

@@ -0,0 +1,37 @@
+---
+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.
+
+<Callout type="warn">
+Deprecated. [`WorkflowModule.forRoot()`](/docs/api-reference/workflow-nest/workflow-module) provides the output directory through dependency injection, which this function predates. It writes process-global state, so two applications in one process (the usual `Test.createTestingModule` setup) overwrite each other's configuration. It is kept only so existing callers keep working.
+</Callout>
+
+`WorkflowModule.forRoot()` still calls this for you, and injected options take precedence over it. Call it yourself only when registering `WorkflowController` without the module. A controller with no configuration at all answers `503` with an explanatory message.
+
+## 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/builder"; // [!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()` through `createRequire`, avoiding ECMAScript module (ESM) and CommonJS (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,46 @@
+---
+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.
+
+The conversion preserves bytes in both directions: request bodies come from `req.rawBody` when the app is created with `{ rawBody: true }`, from a `Buffer`/string body left by a parser, or read directly from the request stream when no parser claimed the content type. Responses are written as bytes, and every `set-cookie` value is kept. See [Raw request bodies](/docs/getting-started/nestjs#raw-request-bodies).
+
+Handlers take `@Res()`, so the application's interceptors and exception filters do not wrap these routes. That is deliberate: the queue and third-party webhook senders key off the exact status and body the workflow runtime produces.
+
+[`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`, `GET`, `HEAD`, `OPTIONS` | Executes workflow and step work items via the combined handler in `workflows.mjs` (step registrations are imported from `steps.mjs` first). `HEAD` is what local port detection probes to identify a workflow server, so all four methods are served. |
+| `/.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. |
+
+A route whose bundle cannot be loaded answers `503` with a message naming the missing file and the build command that produces it, rather than surfacing a raw `ERR_MODULE_NOT_FOUND`.

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

@@ -0,0 +1,134 @@
+---
+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 provides the resolved options under the `WORKFLOW_MODULE_OPTIONS` token, 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.
+
+#### `forRootAsync(options)`
+
+Same as `forRoot`, with the options produced by a factory so they can come from other providers.
+
+{/* @skip-typecheck - config snippet, WorkflowModule imported above */}
+
+```typescript title="src/app.module.ts" lineNumbers
+WorkflowModule.forRootAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    basePath: config.get("API_PREFIX"),
+  }),
+});
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `imports` | `unknown[]` | Optional. Modules whose exported providers the factory injects. |
+| `inject` | `unknown[]` | Optional. Providers passed to `useFactory`, in order. |
+| `useFactory` | `(...args) => WorkflowModuleOptions \| Promise<WorkflowModuleOptions>` | Returns the module options. |
+
+### 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` | `true` when `VERCEL` is set, else `false` | Skip building workflow bundles on startup. The bundles must already exist; startup fails with an explicit error if they do not. |
+| `basePath` | `string` | adopted from `app.setGlobalPrefix()` | Route prefix the workflow endpoints are served under, applied to generated callback and webhook URLs. Set it when a reverse proxy mounts the app on a sub-path NestJS cannot see. |
+| `manageWorldLifecycle` | `boolean` | `false` | Start the target World's background workers with the app and close them on shutdown. Required for self-hosted Worlds, which otherwise never pick up runs. |
+| `preloadBundles` | `boolean` | `false` when `VERCEL` is set, else `true` | Load the generated bundles during startup instead of on the first request. On Vercel, dedicated functions serve the bundles, so there is nothing to preload. |
+| `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` | Deprecated and ignored. Watch mode is not implemented for this builder. Use `nest start --watch`, which re-runs the startup build. |
+| `moduleType` | `'es6' \| 'commonjs'` | `'es6'` | SWC module compilation type. Set to `'commonjs'` if your NestJS project compiles to CommonJS (CJS) through 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()` and `forRootAsync()` return a `DynamicModule` to include in the `imports` array of your root module.
+
+## Injecting the resolved options
+
+Both factories export the resolved options under `WORKFLOW_MODULE_OPTIONS`:
+
+{/* @skip-typecheck - NestJS decorators require special TypeScript config */}
+
+```typescript title="src/some.service.ts" lineNumbers
+import { Inject, Injectable } from "@nestjs/common";
+import {
+  WORKFLOW_MODULE_OPTIONS,
+  type WorkflowModuleOptions,
+} from "workflow/nest";
+
+@Injectable()
+export class SomeService {
+  constructor(
+    @Inject(WORKFLOW_MODULE_OPTIONS)
+    private readonly options: WorkflowModuleOptions
+  ) {}
+}
+```
+
+The older `WORKFLOW_OPTIONS` token resolves to the same value and is kept for compatibility.
+
+## Lifecycle
+
+| Hook | Behaviour |
+| --- | --- |
+| `onModuleInit` | Reconciles the base path against `app.setGlobalPrefix()`, builds the bundles (or verifies they exist when `skipBuild` is set), optionally starts the World, and preloads the bundles. |
+| `onApplicationShutdown` | Closes the World when `manageWorldLifecycle` is set. Call `app.enableShutdownHooks()` so this runs on a signal. |
+
+<Callout type="warn">
+Workflows and steps run outside the NestJS injector, so providers cannot be injected into `"use workflow"` or `"use step"` code. See [NestJS dependency injection is not available in workflows and steps](/docs/getting-started/nestjs#nestjs-dependency-injection-is-not-available-in-workflows-and-steps).
+</Callout>

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

@@ -1,13 +1,13 @@
 ---
 title: withWorkflow
-description: Configure webpack/turbopack to transform workflow directives in Next.js.
+description: Configure webpack and Turbopack to transform workflow directives in Next.js.
 type: reference
 summary: Wrap your Next.js config with withWorkflow to enable workflow directive transformation.
 prerequisites:
   - /docs/getting-started/next
 ---
 
-Configures webpack/turbopack loaders to transform workflow code (`"use step"`/`"use workflow"` directives)
+Configures webpack and Turbopack loaders to transform workflow code (`"use step"` and `"use workflow"` directives).
 
 ## Usage
 
@@ -16,13 +16,13 @@ To enable `"use step"` and `"use workflow"` directives while developing locally
 ```typescript title="next.config.ts" lineNumbers
 import { withWorkflow } from "workflow/next"; // [!code highlight]
 import type { NextConfig } from "next";
- 
+
 const nextConfig: NextConfig = {
   // … rest of your Next.js config
 };
 
 // not required but allows configuring workflow options
-const workflowConfig = {} 
+const workflowConfig = {};
 
 export default withWorkflow(nextConfig, workflowConfig); // [!code highlight]
 ```
@@ -31,12 +31,36 @@ export default withWorkflow(nextConfig, workflowConfig); // [!code highlight]
 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. This ensures the package still gets transformed by the Workflow
-compiler. Remove that package from `serverExternalPackages` in your
+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
+### Workflow discovery in Next.js
+
+`withWorkflow()` discovers workflows by scanning your Next.js entrypoints (App
+Router `route`, `page`, and `layout` files under `app/` or `src/app/`, and any
+file under `pages/` or `src/pages/`) for `start()` calls imported from
+`workflow/api`. The workflow and step files themselves can live anywhere (for
+example `src/workflows/`); they are discovered transitively through imports, as
+long as a `start()` call in an entrypoint statically reaches them.
+
+<Callout type="info">
+Call `start()` from server-side entrypoints, including Route Handlers and Server
+Actions. Don't call workflow functions directly, which bypasses the workflow
+runtime.
+</Callout>
+
+### Next.js server actions and `"use server"`
+
+Don't put a top-level `"use server"` directive in modules imported by workflow
+or step functions. Workflow transformation wraps imported modules in synchronous
+initializers, and Next.js rejects a `"use server"` directive inside that wrapper
+with errors like `Server Actions must be async functions`. Keep `"use server"`
+on the files that define your Server Actions, and move shared logic into
+separate modules that don't carry the directive.
+
+### 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:
 
@@ -68,7 +92,6 @@ const nextConfig: NextConfig = {};
 
 export default withWorkflow(nextConfig, {
   workflows: {
-    lazyDiscovery: false,
     local: {
       port: 4000,
     },
@@ -79,35 +102,34 @@ export default withWorkflow(nextConfig, {
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `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'` | Controls source maps on generated workflow bundles. See [Source maps](#source-maps) below. |
+| `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 so that stack traces from step errors and workflow VM errors point at your source files. The `sourcemap` option lets you change that:
+The step bundle and intermediate workflow bundle default to `'inline'` source maps **in development** (so stack traces from step errors and workflow virtual machine (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). |
+| `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. |
 
-Setting `sourcemap: false` is the main escape hatch for users hitting the Vercel 250MB function size limit — it drops the inline source map from every bundle and also skips the source-map-support runtime shim on the Vercel step function. The tradeoff is that workflow VM stack traces will reference generated code (e.g. `evalmachine.<anonymous>`) rather than your source files.
+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 250 MB function size limit. The tradeoff is that workflow VM stack traces will reference generated code (for example, `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.
+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` > per-bundle default.
+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.
 </Callout>
 
-## Exporting a Function
+## 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`.
@@ -136,4 +158,4 @@ export default async function config(
   }
   return nextConfig;
 }
-``` 
+```

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

@@ -0,0 +1,60 @@
+---
+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 function rules for Vercel Functions (queue triggers and `maxDuration`) on the workflow routes when deploying to Vercel.
+- Uses Nitro's `workspaceDir` as the workflow project root so monorepo apps can import sibling workspace packages without extra workflow config.
+
+## 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 integrated development environment (IDE) IntelliSense. |
+| `runtime` | `string` | — | Node.js runtime version for Vercel Functions (for example, `'nodejs22.x'` or `'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, 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. |
+
+## 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`.

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

@@ -0,0 +1,48 @@
+---
+title: "workflow/nuxt"
+description: Nuxt module for automatic workflow bundling and runtime configuration.
+type: overview
+summary: Explore the Nuxt module that enables workflow directive transformation in Nuxt apps.
+related:
+  - /docs/getting-started/nuxt
+---
+
+Nuxt integration for Workflow SDK. The `workflow/nuxt` entry point's default export is a Nuxt module: it has no callable API. You enable it by adding it to the `modules` array of your Nuxt config and configure it via the `workflow` key.
+
+## Usage
+
+```typescript title="nuxt.config.ts" lineNumbers
+import { defineNuxtConfig } from "nuxt/config";
+
+export default defineNuxtConfig({
+  modules: ["workflow/nuxt"], // [!code highlight]
+  compatibilityDate: "latest",
+});
+```
+
+When enabled, the module:
+
+- Registers the [`workflow/nitro`](/docs/api-reference/workflow-nitro) module on Nuxt's Nitro server, which transforms `"use workflow"` and `"use step"` directives, builds the workflow bundles, and registers the workflow runtime routes under `/.well-known/workflow/v1/`.
+- Configures Vite to bundle (rather than externalize) the Workflow SDK packages in server-side rendering (SSR) mode so workflow code is transformed correctly.
+- Enables the `workflow` TypeScript plugin by default for integrated development environment (IDE) IntelliSense.
+- Uses Nuxt/Nitro's detected `workspaceDir` so monorepo apps can import sibling workspace packages without extra workflow config.
+
+## Module options
+
+Options are read from the `workflow` key of your Nuxt config. The option type is exported as `ModuleOptions`:
+
+```typescript title="nuxt.config.ts" lineNumbers
+import { defineNuxtConfig } from "nuxt/config";
+
+export default defineNuxtConfig({
+  modules: ["workflow/nuxt"],
+  workflow: {
+    typescriptPlugin: false, // [!code highlight]
+  },
+  compatibilityDate: "latest",
+});
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `typescriptPlugin` | `boolean` | `true` | Adds the `workflow` TypeScript plugin to the generated `tsconfig.json` for IDE IntelliSense. Set to `false` to disable it. |

package/docs/api-reference/workflow-observability/hydrate-data.mdx

@@ -0,0 +1,35 @@
+---
+title: hydrateData
+description: Hydrate a single serialized value from workflow storage into a plain JavaScript value.
+type: reference
+summary: Use hydrateData to deserialize a single value when hydrateResourceIO's field mapping doesn't apply.
+related:
+  - /docs/api-reference/workflow-observability/hydrate-resource-io
+  - /docs/api-reference/workflow-observability/observability-revivers
+---
+
+Hydrates (deserializes) a single value that was stored by the workflow runtime. This is the lower-level building block behind [`hydrateResourceIO()`](/docs/api-reference/workflow-observability/hydrate-resource-io). Use it when you have a raw serialized value rather than a whole resource, such as a single field from an event payload.
+
+```typescript lineNumbers
+import { hydrateData, observabilityRevivers } from "workflow/observability"; // [!code highlight]
+declare const serialized: unknown; // @setup
+
+const value = hydrateData(serialized, observabilityRevivers); // [!code highlight]
+```
+
+## API signature
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `value` | `unknown` | The serialized value from workflow storage |
+| `revivers` | `Revivers` | Reviver functions for deserialization. Use [`observabilityRevivers`](/docs/api-reference/workflow-observability/observability-revivers) for standard use. |
+
+### Returns
+
+The hydrated plain JavaScript value. The input is handled by shape:
+
+- Format-prefixed binary data (`Uint8Array`) is decoded and parsed from the [devalue](https://github.com/Rich-Harris/devalue) format.
+- Encrypted data is returned as-is (a raw `Uint8Array`). See [Encrypted data](/docs/api-reference/workflow-observability#encrypted-data).
+- Already-plain values (numbers, strings, and `null`) are returned unchanged.