Nitro

npm install workflow

yarn add workflow

pnpm add workflow

import { defineConfig } from 'nitro';

export default defineConfig({
  modules: ['workflow/nitro'],
  serverDir: './server',
});

export default defineConfig({
  modules: ['workflow/nitro'],
  workflow: {
    typescriptPlugin: true,  // Enable TypeScript IntelliSense
  },
});

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

​

How it works

• 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

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

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

nitro dev

• Build workflows on startup
• Watch for changes and rebuild automatically
• Provide HMR for workflow files

​

Production

nitro build

• Generates Vercel function configurations
• Sets up queue triggers for workflow execution
• Configures retry policies

​

Advanced usage

​

Exposing the manifest

WORKFLOW_PUBLIC_MANIFEST=1 nitro dev

​

Using with other frameworks

• 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