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

# @workflow/nest

> NestJS integration for Workflow DevKit

## Installation

```bash theme={null}
npm install @workflow/nest
```

## Usage

Import and configure the `WorkflowModule` in your NestJS application:

```typescript app.module.ts theme={null}
import { Module } from '@nestjs/common';
import { WorkflowModule } from '@workflow/nest';

@Module({
  imports: [WorkflowModule.forRoot()],
})
export class AppModule {}
```

## API

### `WorkflowModule`

NestJS module that provides workflow functionality.

#### `WorkflowModule.forRoot(options?)`

Configures and returns the workflow module.

<ParamField path="options" type="WorkflowModuleOptions">
  Module configuration options.
</ParamField>

<ParamField path="options.workingDir" type="string">
  Working directory for the NestJS application.

  **Default:** `process.cwd()`
</ParamField>

<ParamField path="options.dirs" type="string[]">
  Directories to scan for workflow files.

  **Default:** `['src']`
</ParamField>

<ParamField path="options.outDir" type="string">
  Output directory for generated workflow bundles.

  **Default:** `.nestjs/workflow`
</ParamField>

<ParamField path="options.watch" type="boolean">
  Enable watch mode for development.

  **Default:** `false`
</ParamField>

<ParamField path="options.moduleType" type="'es6' | 'commonjs'">
  SWC module compilation type.

  Set to `'commonjs'` if your NestJS project compiles to CJS via SWC. When `'commonjs'`, the builder rewrites externalized imports in the steps bundle to use `require()` via `createRequire`, avoiding ESM/CJS named-export interop issues.

  **Default:** `'es6'`
</ParamField>

<ParamField path="options.distDir" type="string">
  Directory where NestJS compiles `.ts` source files to `.js` (relative to `workingDir`).

  Used when `moduleType` is `'commonjs'` to resolve compiled file paths. This should match the `outDir` in your `tsconfig.json`.

  **Default:** `'dist'`
</ParamField>

<ParamField path="options.skipBuild" type="boolean">
  Skip building workflow bundles (useful in production when bundles are pre-built).

  **Default:** `false`
</ParamField>

### `WorkflowController`

Controller that handles the well-known workflow endpoints. Automatically registered by `WorkflowModule.forRoot()`.

#### Routes

* `POST /.well-known/workflow/v1/step` - Step execution endpoint
* `POST /.well-known/workflow/v1/flow` - Workflow execution endpoint
* `ALL /.well-known/workflow/v1/webhook/:token` - Webhook endpoint
* `GET /.well-known/workflow/v1/manifest.json` - Workflow manifest (when `WORKFLOW_PUBLIC_MANIFEST=1`)

### `NestLocalBuilder`

Builder class for generating workflow bundles in NestJS applications.

```typescript theme={null}
import { NestLocalBuilder } from '@workflow/nest';

const builder = new NestLocalBuilder({
  workingDir: process.cwd(),
  outDir: '.nestjs/workflow',
  dirs: ['src'],
});

await builder.build();
```

### `configureWorkflowController(outDir)`

Configures the workflow controller with the output directory. Called automatically by `WorkflowModule.forRoot()`.

<ParamField path="outDir" type="string" required>
  Output directory where workflow bundles are generated.
</ParamField>

## Configuration Examples

### Basic Configuration

```typescript app.module.ts theme={null}
import { Module } from '@nestjs/common';
import { WorkflowModule } from '@workflow/nest';

@Module({
  imports: [WorkflowModule.forRoot()],
})
export class AppModule {}
```

### Custom Directories

```typescript app.module.ts theme={null}
import { Module } from '@nestjs/common';
import { WorkflowModule } from '@workflow/nest';

@Module({
  imports: [
    WorkflowModule.forRoot({
      dirs: ['src/workflows', 'src/modules'],
      outDir: 'dist/workflow',
    }),
  ],
})
export class AppModule {}
```

### CommonJS Configuration

For NestJS projects using SWC to compile to CommonJS:

```typescript app.module.ts theme={null}
import { Module } from '@nestjs/common';
import { WorkflowModule } from '@workflow/nest';

@Module({
  imports: [
    WorkflowModule.forRoot({
      moduleType: 'commonjs',
      distDir: 'dist',
    }),
  ],
})
export class AppModule {}
```

### Production Configuration

```typescript app.module.ts theme={null}
import { Module } from '@nestjs/common';
import { WorkflowModule } from '@workflow/nest';

const isProduction = process.env.NODE_ENV === 'production';

@Module({
  imports: [
    WorkflowModule.forRoot({
      skipBuild: isProduction,
      watch: !isProduction,
    }),
  ],
})
export class AppModule {}
```

## How It Works

1. **Module Initialization**: `WorkflowModule.forRoot()` creates a `NestLocalBuilder` instance
2. **Build on Init**: When the module initializes (`onModuleInit`), it builds workflow bundles
3. **Controller Registration**: Registers `WorkflowController` with well-known workflow routes
4. **Request Handling**: Controller dynamically imports generated bundles and handles request/response conversion

### Express/Fastify Compatibility

The `WorkflowController` automatically detects and works with both Express and Fastify adapters:

* Converts platform-specific requests to Web API `Request`
* Converts Web API `Response` back to platform-specific response

## CommonJS Interop

When using `moduleType: 'commonjs'`, the builder:

1. Generates ESM workflow bundles
2. Rewrites externalized `.ts`/`.tsx` imports to use `require()` via `createRequire`
3. Points imports to compiled `.js` files in `distDir`

This avoids ESM/CJS interop issues with SWC's `_export()` wrapper pattern.

## Build Queue

Uses `createBuildQueue()` to prevent concurrent builds when rebuilding workflows.


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