NestJS

This guide shows you how to install Workflow DevKit in a NestJS project.

Install dependencies

Install the required packages:

npm install workflow @nestjs/common @nestjs/core
npm install -D @swc/cli @swc/core

yarn add workflow @nestjs/common @nestjs/core
yarn add -D @swc/cli @swc/core

pnpm add workflow @nestjs/common @nestjs/core
pnpm add -D @swc/cli @swc/core

NestJS with Workflow DevKit requires SWC for compilation. The @swc/cli and @swc/core packages are peer dependencies.

Initialize SWC configuration

Run the Workflow NestJS CLI to set up SWC:

npx workflow-nest init

This creates a .swcrc file with the Workflow plugin configured:

.swcrc

{
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "decorators": true
    },
    "transform": {
      "decoratorMetadata": true
    },
    "experimental": {
      "plugins": [
        ["@workflow/swc-plugin", {}]
      ]
    }
  }
}

Configure the Workflow module

Import and configure the Workflow module in your app:

src/app.module.ts

import { Module } from '@nestjs/common';
import { WorkflowModule } from 'workflow/nest';
import { AppController } from './app.controller';

@Module({
  imports: [
    WorkflowModule.forRoot({
      // Optional: customize output directory
      outDir: '.nestjs/workflow',
      // Optional: skip builds in production
      skipBuild: false,
    })
  ],
  controllers: [AppController],
})
export class AppModule {}

The WorkflowModule.forRoot() method:

Registers the WorkflowController for handling workflow endpoints
Configures the builder to compile workflows
Sets up the output directory for workflow bundles

Update NestJS CLI config

Configure NestJS to use SWC for building:

nest-cli.json

{
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "builder": "swc",
    "typeCheck": true
  }
}

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 NestJS integration:

Module system: Uses NestJS’s module system for dependency injection
Builder: Compiles workflows during module initialization using NestLocalBuilder
Controller: Provides a WorkflowController that handles workflow endpoints:
- POST /.well-known/workflow/v1/step - Step execution
- POST /.well-known/workflow/v1/flow - Workflow execution
- ALL /.well-known/workflow/v1/webhook/:token - Webhook handling
- GET /.well-known/workflow/v1/manifest.json - Manifest (when WORKFLOW_PUBLIC_MANIFEST=1)
Request conversion: Automatically converts Express/Fastify requests to Web API Request objects
Build queue: Prevents concurrent builds during module initialization

Example workflow

src/workflows/notification.ts

import { sleep } from "workflow";

export async function sendNotification(userId: string, message: string) {
  "use workflow";

  await validateUser(userId);
  await sendEmail(userId, message);
  await sleep("1 hour");
  await sendFollowUp(userId);

  return { userId, status: "sent" };
}

async function validateUser(userId: string) {
  "use step";
  console.log(`Validating user ${userId}`);
}

async function sendEmail(userId: string, message: string) {
  "use step";
  console.log(`Sending email to user ${userId}: ${message}`);
}

async function sendFollowUp(userId: string) {
  "use step";
  console.log(`Sending follow-up to user ${userId}`);
}

Triggering workflows

Start workflows from controllers:

src/app.controller.ts

import { Controller, Post, Body } from '@nestjs/common';
import { start } from 'workflow/api';
import { sendNotification } from './workflows/notification';

@Controller()
export class AppController {
  @Post('notify')
  async notify(@Body() body: { userId: string; message: string }) {
    const { userId, message } = body;
    await start(sendNotification, [userId, message]);
    return { message: "Notification workflow started" };
  }
}

Development

Run the development server:

npm run start:dev

Trigger a workflow:

curl -X POST --json '{"userId":"123","message":"Hello!"}' http://localhost:3000/notify

Production

Build for production:

npm run build

Optionally skip workflow builds in production if workflows are pre-built:

src/app.module.ts

WorkflowModule.forRoot({
  skipBuild: process.env.NODE_ENV === 'production',
})

Configuration options

WorkflowModuleOptions

interface WorkflowModuleOptions {
  // Working directory for the builder (default: process.cwd())
  workingDir?: string;
  
  // Output directory for workflow bundles (default: .nestjs/workflow)
  outDir?: string;
  
  // Skip building workflow bundles (default: false)
  skipBuild?: boolean;
}

Getting Started

Installation

Core Concepts

Building AI Agents

How It Works

Deployment

Observability

Testing

Error Reference

How it works

Example workflow

Triggering workflows

Development

Production

Configuration options

WorkflowModuleOptions

Next steps

Core Concepts

API Reference

​How it works

​Example workflow

​Triggering workflows

​Development

​Production

​Configuration options

​WorkflowModuleOptions

​Next steps

Core Concepts

API Reference

How it works

Example workflow

Triggering workflows

Development

Production

Configuration options

WorkflowModuleOptions

Next steps