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

> Next.js integration for Workflow DevKit

## Installation

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

## Usage

Wrap your Next.js configuration with `withWorkflow` to enable workflow functionality:

```javascript next.config.js theme={null}
import { withWorkflow } from '@workflow/next';

export default withWorkflow({
  // Your Next.js config
});
```

### With Async Config Function

```javascript next.config.js theme={null}
import { withWorkflow } from '@workflow/next';

export default withWorkflow(
  async (phase, { defaultConfig }) => {
    return {
      // Your Next.js config
    };
  }
);
```

## API

### `withWorkflow(nextConfig, options?)`

Wraps your Next.js configuration to add workflow support.

<ParamField path="nextConfig" type="NextConfig | Function" required>
  Your Next.js configuration object or async function that returns a configuration.

  When a function is provided, it receives:

  * `phase`: The build phase (e.g., `PHASE_DEVELOPMENT_SERVER`)
  * `ctx.defaultConfig`: Default Next.js configuration
</ParamField>

<ParamField path="options" type="object">
  Workflow configuration options.
</ParamField>

<ParamField path="options.workflows" type="object">
  Workflow-specific settings.
</ParamField>

<ParamField path="options.workflows.lazyDiscovery" type="boolean">
  Enable lazy discovery of workflows. When enabled, workflows are discovered on-demand rather than at build time.

  Sets `WORKFLOW_NEXT_LAZY_DISCOVERY=1` environment variable.
</ParamField>

<ParamField path="options.workflows.local" type="object">
  Local development configuration.
</ParamField>

<ParamField path="options.workflows.local.port" type="number">
  Port number for the local development server.

  Sets the `PORT` environment variable.
</ParamField>

<ParamField path="options.workflows.local.dataDir" type="string">
  Directory for storing workflow data in local development.

  Default: `.next/workflow-data`
</ParamField>

## Configuration Examples

### Basic Configuration

```javascript next.config.js theme={null}
import { withWorkflow } from '@workflow/next';

export default withWorkflow({
  reactStrictMode: true,
});
```

### With Lazy Discovery

```javascript next.config.js theme={null}
import { withWorkflow } from '@workflow/next';

export default withWorkflow(
  {
    reactStrictMode: true,
  },
  {
    workflows: {
      lazyDiscovery: true,
    },
  }
);
```

### Custom Local Development

```javascript next.config.js theme={null}
import { withWorkflow } from '@workflow/next';

export default withWorkflow(
  {
    reactStrictMode: true,
  },
  {
    workflows: {
      local: {
        port: 3001,
        dataDir: '.workflow-data',
      },
    },
  }
);
```

## Runtime Exports

The package also exports runtime utilities:

```javascript theme={null}
import { /* runtime exports */ } from '@workflow/next/runtime';
```

## Loader Export

Internal loader for webpack/turbopack integration:

```javascript theme={null}
import loader from '@workflow/next/loader';
```

## How It Works

`withWorkflow` automatically configures:

1. **Webpack**: Adds a custom loader to transform workflow files
2. **Turbopack**: Configures rules for `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.mts`, `.cjs`, `.cts` files
3. **Builder**: Discovers and builds workflows from `pages/`, `app/`, `src/pages/`, and `src/app/` directories
4. **Environment**: Sets up appropriate world target (local or Vercel)

### Supported Next.js Versions

Requires Next.js 13 or higher.

### Deferred Builder (Next.js 16+)

For Next.js v16.0.0 and above, the integration uses a deferred builder that integrates with Next.js's experimental deferred entries feature for better performance.

## Environment Variables

The integration automatically sets these environment variables:

* `WORKFLOW_TARGET_WORLD`: Set to `local` (development) or `vercel` (production)
* `WORKFLOW_LOCAL_DATA_DIR`: Directory for local workflow data
* `PORT`: Development server port (if configured)
* `WORKFLOW_NEXT_LAZY_DISCOVERY`: Enable lazy workflow discovery


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