Skip to main content
This guide shows you how to install Workflow DevKit in a Fastify application using Nitro as the build system.
1

Install dependencies

Install the required packages:
npm install workflow fastify nitro rollup
Nitro provides the build system needed to compile workflows. Learn more at nitro.build.
2

Configure Nitro

Create a nitro.config.ts file with the Workflow module:
nitro.config.ts
import { defineNitroConfig } from 'nitro/config';

export default defineNitroConfig({
  modules: ['workflow/nitro'],
  vercel: { entryFormat: 'node' },
  routes: {
    '/**': { handler: './src/index.ts', format: 'node' },
  },
});
This configuration:
  • Enables the Workflow Nitro module
  • Routes all requests to your Fastify app
  • Uses Node.js format for compatibility with Fastify
3

Create your Fastify app

Create src/index.ts with your Fastify application:
src/index.ts
import Fastify from 'fastify';
import { start } from 'workflow/api';
import { handleUserSignup } from '../workflows/user-signup.js';

const server = Fastify({
  logger: true,
});

// Configure JSON parsing for empty requests
server.addContentTypeParser(
  'application/json',
  { parseAs: 'string' },
  (req, body, done) => {
    const text = typeof body === 'string' ? body : body.toString();
    if (!text) return done(null, {});
    try {
      done(null, JSON.parse(text));
    } catch (error) {
      done(error as Error);
    }
  }
);

server.post('/api/signup', async (req, reply) => {
  const { email } = req.body as { email: string };
  await start(handleUserSignup, [email]);
  return reply.send({ message: "User signup workflow started" });
});

await server.ready();

export default (req: any, res: any) => {
  server.server.emit('request', req, res);
};
4

Update package.json scripts

Add development and build scripts:
package.json
{
  "scripts": {
    "dev": "nitro dev",
    "build": "nitro build",
    "start": "node .output/server/index.mjs"
  }
}
5

Enable TypeScript support (Optional)

Add the Workflow TypeScript plugin to your tsconfig.json for IntelliSense:
tsconfig.json
{
  "compilerOptions": {
    "plugins": [
      {
        "name": "workflow"
      }
    ]
  }
}

​
How it works

The Fastify + Nitro integration:
  • Uses Nitro’s build system to compile workflows
  • Generates workflow route handlers at .well-known/workflow/v1/*
  • Supports both development (with HMR) and production builds
  • Routes all non-workflow requests to your Fastify app
  • Automatically handles workflow execution and resumption

​
Example workflow

workflows/user-signup.ts
import { sleep } from "workflow";

export async function handleUserSignup(email: string) {
  "use workflow";

  const user = await createUser(email);
  await sendWelcomeEmail(user);
  await sleep("1 day");
  await sendOnboardingEmail(user);

  return { userId: user.id, status: "onboarded" };
}

async function createUser(email: string) {
  "use step";
  console.log(`Creating user with email: ${email}`);
  return { id: crypto.randomUUID(), email };
}

async function sendWelcomeEmail(user: { id: string; email: string }) {
  "use step";
  console.log(`Sending welcome email to user: ${user.id}`);
}

async function sendOnboardingEmail(user: { id: string; email: string }) {
  "use step";
  console.log(`Sending onboarding email to user: ${user.id}`);
}

​
Development

Run the development server: 
npm run dev
Trigger a workflow: 
curl -X POST --json '{"email":"[email protected]"}' http://localhost:3000/api/signup

​
Production

Build and start the production server: 
npm run build
npm start

​
Next steps

Core Concepts

Learn about workflows and steps

Nitro Integration

Learn more about the Nitro integration

Build docs developers (and LLMs) love

Get started for freeTalk to us