Skip to main content

​
Installation

npm install @workflow/nitro

​
Usage

Add the workflow module to your Nitro configuration:
nitro.config.ts
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:
nitro.config.ts
import { defineNitroConfig } from 'nitro/config';

export default defineNitroConfig({
  modules: ['@workflow/nitro'],
  workflow: {
    dirs: ['workflows'],
    typescriptPlugin: true,
  },
});
​
workflow.dirs
string[]
Directories to scan for workflows and steps.By default, the workflows/ directory will be scanned from root and all layer source directories.
​
workflow.typescriptPlugin
boolean
Enable workflow TypeScript plugin in generated tsconfig.json.Default: false
​
workflow.runtime
string
Node.js runtime version for Vercel Functions.Examples:
  • "nodejs22.x"
  • "nodejs24.x"

​
Configuration Examples

​
Basic Configuration

nitro.config.ts
import { defineNitroConfig } from 'nitro/config';

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

​
Custom Directories

nitro.config.ts
import { defineNitroConfig } from 'nitro/config';

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

​
Enable TypeScript Plugin

nitro.config.ts
import { defineNitroConfig } from 'nitro/config';

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

​
Vercel Runtime Configuration

nitro.config.ts
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: 
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: 
{
  "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.

Build docs developers (and LLMs) love

Get started for freeTalk to us