> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vercel/workflow/llms.txt
> Use this file to discover all available pages before exploring further.

# @workflow/nitro

> Nitro module for Workflow DevKit

## Installation

```bash theme={null}
npm install @workflow/nitro
```

## Usage

Add the workflow module to your Nitro configuration:

```typescript nitro.config.ts theme={null}
import { defineNitroConfig } from 'nitro/config';

export default defineNitroConfig({
  modules: ['@workflow/nitro'],
});
```

## API

### Module Options

Configure the Nitro module via the `workflow` option in your Nitro config:

```typescript nitro.config.ts theme={null}
import { defineNitroConfig } from 'nitro/config';

export default defineNitroConfig({
  modules: ['@workflow/nitro'],
  workflow: {
    dirs: ['workflows'],
    typescriptPlugin: true,
  },
});
```

<ParamField path="workflow.dirs" type="string[]">
  Directories to scan for workflows and steps.

  By default, the `workflows/` directory will be scanned from root and all layer source directories.
</ParamField>

<ParamField path="workflow.typescriptPlugin" type="boolean">
  Enable workflow TypeScript plugin in generated `tsconfig.json`.

  **Default:** `false`
</ParamField>

<ParamField path="workflow.runtime" type="string">
  Node.js runtime version for Vercel Functions.

  **Examples:**

  * `"nodejs22.x"`
  * `"nodejs24.x"`
</ParamField>

## Configuration Examples

### Basic Configuration

```typescript nitro.config.ts theme={null}
import { defineNitroConfig } from 'nitro/config';

export default defineNitroConfig({
  modules: ['@workflow/nitro'],
});
```

### Custom Directories

```typescript nitro.config.ts theme={null}
import { defineNitroConfig } from 'nitro/config';

export default defineNitroConfig({
  modules: ['@workflow/nitro'],
  workflow: {
    dirs: ['server/workflows', 'app/workflows'],
  },
});
```

### Enable TypeScript Plugin

```typescript nitro.config.ts theme={null}
import { defineNitroConfig } from 'nitro/config';

export default defineNitroConfig({
  modules: ['@workflow/nitro'],
  workflow: {
    typescriptPlugin: true,
  },
});
```

### Vercel Runtime Configuration

```typescript nitro.config.ts theme={null}
import { defineNitroConfig } from 'nitro/config';

export default defineNitroConfig({
  modules: ['@workflow/nitro'],
  workflow: {
    runtime: 'nodejs22.x',
  },
});
```

## How It Works

### Development Mode

1. **Transform Plugin**: Adds `workflowTransformPlugin` at the beginning of Rollup plugins
2. **Externalization**: Externalizes `.nitro/workflow` directory to prevent dev reloads
3. **Build Hook**: Runs `LocalBuilder` during `build:before` hook
4. **HMR**: Hooks into `dev:reload` to rebuild workflows on file changes
5. **Virtual Handlers**: Creates virtual route handlers for workflow endpoints

### Production (Non-Vercel)

1. **Build**: Generates workflow bundles via `LocalBuilder`
2. **Routes**: Creates handlers for:
   * `/.well-known/workflow/v1/webhook/:token`
   * `/.well-known/workflow/v1/step`
   * `/.well-known/workflow/v1/flow`
   * `/.well-known/workflow/v1/manifest.json` (when `WORKFLOW_PUBLIC_MANIFEST=1`)

### Production (Vercel)

1. **Vercel Builder**: Runs `VercelBuilder` during `compiled` hook
2. **Build Output API**: Generates Vercel Build Output API compatible functions
3. **Preset Detection**: Automatically detected via `nitro.options.preset === 'vercel'`

## Generated Routes

The module creates the following API routes:

* `POST /.well-known/workflow/v1/flow` - Workflow execution
* `POST /.well-known/workflow/v1/step` - Step execution
* `POST /.well-known/workflow/v1/webhook/:token` - Webhook handler
* `GET /.well-known/workflow/v1/manifest.json` - Workflow manifest (optional)

## Manifest Handling

### Development

Manifest is read from disk at request time using `readFileSync`.

### Production

Manifest content is inlined into the handler during build via `writeManifestHandler()`, called after the builder generates the manifest.

To expose the manifest endpoint, set:

```bash theme={null}
WORKFLOW_PUBLIC_MANIFEST=1
```

## Nitro Version Compatibility

Supports both Nitro v2 (legacy) and Nitro v3+:

* **Nitro v2**: Uses `fromWebHandler` from `h3` to wrap handlers
* **Nitro v3+**: Uses native web handlers directly

The module automatically detects the version via the `nitro.routing` property.

## TypeScript Plugin

When `workflow.typescriptPlugin: true`, adds the workflow TypeScript plugin to `tsconfig.json`:

```json theme={null}
{
  "compilerOptions": {
    "plugins": [
      { "name": "workflow" }
    ]
  }
}
```

This enables IDE integration and type checking for workflow directives.

## Build Directory Structure

```
.nitro/
└── workflow/
    ├── workflows.mjs      # Workflow bundle
    ├── steps.mjs          # Steps bundle
    ├── webhook.mjs        # Webhook handler
    ├── manifest.json      # Workflow manifest
    └── manifest-handler.mjs  # Manifest handler (prod only)
```

## Exclusions

The transform plugin excludes the `.nitro/workflow` directory from re-transformation to prevent issues with bundler variable renaming.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.