@workflow/nitro

​

Installation

npm install @workflow/nitro

​

Usage

import { defineNitroConfig } from 'nitro/config';

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

​

API

​

Module Options

import { defineNitroConfig } from 'nitro/config';

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

​

Configuration Examples

​

Basic Configuration

import { defineNitroConfig } from 'nitro/config';

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

​

Custom Directories

import { defineNitroConfig } from 'nitro/config';

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

​

Enable TypeScript Plugin

import { defineNitroConfig } from 'nitro/config';

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

​

Vercel Runtime Configuration

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

• 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

​

Production

WORKFLOW_PUBLIC_MANIFEST=1

​

Nitro Version Compatibility

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

​

TypeScript Plugin

{
  "compilerOptions": {
    "plugins": [
      { "name": "workflow" }
    ]
  }
}

​

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