> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vercel/workflow/llms.txt
> Use this file to discover all available pages before exploring further.

# NestJS

> Install and configure Workflow DevKit in your NestJS application

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

<Steps>
  <Step title="Install dependencies">
    Install the required packages:

    <CodeGroup>
      ```bash npm theme={null}
      npm install workflow @nestjs/common @nestjs/core
      npm install -D @swc/cli @swc/core
      ```

      ```bash yarn theme={null}
      yarn add workflow @nestjs/common @nestjs/core
      yarn add -D @swc/cli @swc/core
      ```

      ```bash pnpm theme={null}
      pnpm add workflow @nestjs/common @nestjs/core
      pnpm add -D @swc/cli @swc/core
      ```
    </CodeGroup>

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

  <Step title="Initialize SWC configuration">
    Run the Workflow NestJS CLI to set up SWC:

    ```bash theme={null}
    npx workflow-nest init
    ```

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

    ```json .swcrc theme={null}
    {
      "jsc": {
        "parser": {
          "syntax": "typescript",
          "decorators": true
        },
        "transform": {
          "decoratorMetadata": true
        },
        "experimental": {
          "plugins": [
            ["@workflow/swc-plugin", {}]
          ]
        }
      }
    }
    ```
  </Step>

  <Step title="Configure the Workflow module">
    Import and configure the Workflow module in your app:

    ```typescript src/app.module.ts theme={null}
    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
  </Step>

  <Step title="Update NestJS CLI config">
    Configure NestJS to use SWC for building:

    ```json nest-cli.json theme={null}
    {
      "collection": "@nestjs/schematics",
      "sourceRoot": "src",
      "compilerOptions": {
        "builder": "swc",
        "typeCheck": true
      }
    }
    ```
  </Step>

  <Step title="Enable TypeScript support (Optional)">
    Add the Workflow TypeScript plugin to your `tsconfig.json` for IntelliSense:

    ```json tsconfig.json theme={null}
    {
      "compilerOptions": {
        "plugins": [
          {
            "name": "workflow"
          }
        ]
      }
    }
    ```
  </Step>
</Steps>

## 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

```typescript src/workflows/notification.ts theme={null}
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:

```typescript src/app.controller.ts theme={null}
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:

```bash theme={null}
npm run start:dev
```

Trigger a workflow:

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

## Production

Build for production:

```bash theme={null}
npm run build
```

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

```typescript src/app.module.ts theme={null}
WorkflowModule.forRoot({
  skipBuild: process.env.NODE_ENV === 'production',
})
```

## Configuration options

### WorkflowModuleOptions

```typescript theme={null}
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;
}
```

## Next steps

<CardGroup cols={2}>
  <Card title="Core Concepts" href="/concepts/workflows-and-steps">
    Learn about workflows and steps
  </Card>

  <Card title="API Reference" href="/api-reference/integrations/nest">
    View the full NestJS API reference
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.