with-workflow.mdx

title	withWorkflow
description	Configure webpack/turbopack to transform workflow directives in Next.js.
type	reference
summary	Wrap your Next.js config with withWorkflow to enable workflow directive transformation.
prerequisites	/docs/getting-started/next

Configures webpack/turbopack loaders to transform workflow code ("use step"/"use workflow" directives)

Usage

To enable "use step" and "use workflow" directives while developing locally or deploying to production, wrap your nextConfig with withWorkflow.

import { withWorkflow } from "workflow/next"; // [!code highlight]
import type { NextConfig } from "next";
 
const nextConfig: NextConfig = {
  // … rest of your Next.js config
};

// not required but allows configuring workflow options
const workflowConfig = {} 

export default withWorkflow(nextConfig, workflowConfig); // [!code highlight]

If you are exporting a function in your next.config you will need to ensure you call the function returned from withWorkflow.

import { NextConfig } from "next";
import { withWorkflow } from "workflow/next";
import createNextIntlPlugin from "next-intl/plugin";

const withNextIntl = createNextIntlPlugin();

export default async function config(
  phase: string,
  ctx: {
    defaultConfig: NextConfig
  }
): Promise<NextConfig> {
  let nextConfig: NextConfig | typeof config = {};

  for (const configModifier of [withNextIntl, withWorkflow]) {
    nextConfig = configModifier(nextConfig);

    if (typeof nextConfig === "function") {
      nextConfig = await nextConfig(phase, ctx);
    }
  }
  return nextConfig;
}

Configuration

The second argument to withWorkflow accepts the following options:

workflows.dirs

Directories containing files with use workflow directives.

By default, withWorkflow uses Next.js entrypoint directories (pages, app, src/pages, src/app) as starting points and traces their imports to discover workflow files. If your workflows live in dedicated directories, use this option to point directly at them — avoiding the need to crawl the entire app's import tree.

• Type: string[]

import { withWorkflow } from "workflow/next";
import type { NextConfig } from "next";

const nextConfig: NextConfig = {};

export default withWorkflow(nextConfig, {
  workflows: {
    dirs: ['workflows', 'src/workflows'], // [!code highlight]
  },
});

workflows.local.port

Port for the local workflow server during development.

• Type: number
• Default: Uses the PORT environment variable

workflows.local.dataDir

Directory for storing local workflow data during development.

• Type: string
• Default: '.next/workflow-data'