Skip to main content

​
Installation

npm install @workflow/next

​
Usage

Wrap your Next.js configuration with withWorkflow to enable workflow functionality:
next.config.js
import { withWorkflow } from '@workflow/next';

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

​
With Async Config Function

next.config.js
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.
​
nextConfig
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
​
options
object
Workflow configuration options.
​
options.workflows
object
Workflow-specific settings.
​
options.workflows.lazyDiscovery
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.
​
options.workflows.local
object
Local development configuration.
​
options.workflows.local.port
number
Port number for the local development server.Sets the PORT environment variable.
​
options.workflows.local.dataDir
string
Directory for storing workflow data in local development.Default: .next/workflow-data

​
Configuration Examples

​
Basic Configuration

next.config.js
import { withWorkflow } from '@workflow/next';

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

​
With Lazy Discovery

next.config.js
import { withWorkflow } from '@workflow/next';

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

​
Custom Local Development

next.config.js
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: 
import { /* runtime exports */ } from '@workflow/next/runtime';

​
Loader Export

Internal loader for webpack/turbopack integration: 
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

Build docs developers (and LLMs) love

Get started for freeTalk to us