Skip to main content
This guide shows you how to install Workflow DevKit in a Nitro project.
1

Install dependencies

Install the workflow package:
npm install workflow
2

Configure Nitro

Add the Workflow module to your Nitro config:
nitro.config.ts
import { defineConfig } from 'nitro';

export default defineConfig({
  modules: ['workflow/nitro'],
  serverDir: './server',
});
The Workflow module automatically:
  • Adds the Rollup transform plugin to process workflow directives
  • Builds workflow bundles during development and production
  • Generates route handlers at .well-known/workflow/v1/*
  • Supports hot module replacement in development

​
Configuration Options

You can configure the TypeScript plugin:
nitro.config.ts
export default defineConfig({
  modules: ['workflow/nitro'],
  workflow: {
    typescriptPlugin: true,  // Enable TypeScript IntelliSense
  },
});
3

Enable TypeScript support (Optional)

The TypeScript plugin can be enabled via Nitro config (shown above) or directly in tsconfig.json:
tsconfig.json
{
  "compilerOptions": {
    "plugins": [
      {
        "name": "workflow"
      }
    ]
  }
}

​
How it works

The Nitro integration:
  • Transform plugin: Uses @workflow/rollup to transform workflow and step functions
  • Build hooks: Builds workflows during build:before and supports HMR via dev:reload
  • Route generation: Creates virtual handlers for workflow endpoints:
    • /.well-known/workflow/v1/webhook/:token - Webhook handling
    • /.well-known/workflow/v1/step - Step execution
    • /.well-known/workflow/v1/flow - Workflow execution
    • /.well-known/workflow/v1/manifest.json - Manifest (when WORKFLOW_PUBLIC_MANIFEST=1)
  • Vercel integration: Automatically generates Vercel functions when deploying with preset: 'vercel'
  • Externalization: Excludes generated workflow bundles from dev reloads for better performance

​
Example workflow

server/workflows/order-processing.ts
import { sleep } from "workflow";

export async function processOrder(orderId: string) {
  "use workflow";

  const order = await fetchOrder(orderId);
  await validatePayment(order);
  await sleep("5m");
  await shipOrder(order);

  return { orderId, status: "shipped" };
}

async function fetchOrder(orderId: string) {
  "use step";
  console.log(`Fetching order ${orderId}`);
  return { id: orderId, amount: 99.99 };
}

async function validatePayment(order: { id: string; amount: number }) {
  "use step";
  console.log(`Validating payment for order ${order.id}`);
}

async function shipOrder(order: { id: string; amount: number }) {
  "use step";
  console.log(`Shipping order ${order.id}`);
}

​
Triggering workflows

Start workflows from API routes:
server/api/orders.post.ts
import { start } from 'workflow/api';
import { defineEventHandler } from 'h3';
import { processOrder } from '../workflows/order-processing';

export default defineEventHandler(async (event) => {
  const { orderId } = await readBody(event);
  await start(processOrder, [orderId]);
  return { message: "Order processing started" };
});

​
Development

Run the development server: 
nitro dev
The Workflow module will:
  • Build workflows on startup
  • Watch for changes and rebuild automatically
  • Provide HMR for workflow files

​
Production

Build for production: 
nitro build
For Vercel deployment, the module automatically:
  • Generates Vercel function configurations
  • Sets up queue triggers for workflow execution
  • Configures retry policies

​
Advanced usage

​
Exposing the manifest

Set the WORKFLOW_PUBLIC_MANIFEST environment variable to expose the workflow manifest: 
WORKFLOW_PUBLIC_MANIFEST=1 nitro dev
The manifest will be available at /.well-known/workflow/v1/manifest.json.

​
Using with other frameworks

The Nitro integration is used internally by:
  • Express: Via custom routes configuration
  • Fastify: Via custom routes configuration
  • Hono: Via custom routes configuration
  • Nuxt: Via the Nuxt module which wraps Nitro

​
Next steps

Core Concepts

Learn about workflows and steps

API Reference

View the full Nitro API reference

Build docs developers (and LLMs) love

Get started for freeTalk to us