withWorkflow

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.

next.config.ts

import { withWorkflow } from "workflow/next"; 
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);

Monorepos and Workspace Imports

If your Next.js app lives in a subdirectory such as apps/web and your workflows import code from sibling workspace packages, set outputFileTracingRoot to the workspace root. withWorkflow() uses this value as the builder project root so workflow transforms can resolve workspace module specifiers correctly.

apps/web/next.config.ts

import { resolve } from "node:path";
import type { NextConfig } from "next";
import { withWorkflow } from "workflow/next";

const nextConfig: NextConfig = {
  outputFileTracingRoot: resolve(process.cwd(), "../.."),
};

export default withWorkflow(nextConfig);

Use the smallest directory that contains every workspace package imported by your workflows. If your app already lives at the repository root, you do not need to set outputFileTracingRoot.

Options

withWorkflow accepts an optional second argument to control local development behavior.

next.config.ts

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

const nextConfig: NextConfig = {};

export default withWorkflow(nextConfig, {
  workflows: {
    lazyDiscovery: true,
    local: {
      port: 4000,
    },
  },
});

Option	Type	Default	Description
`workflows.lazyDiscovery`	`boolean`	`false`	When `true`, defers workflow discovery until files are requested instead of scanning eagerly at startup. Useful for large projects where startup time matters.
`workflows.local.port`	`number`	—	Overrides the `PORT` environment variable for local development. Has no effect when deployed to Vercel.

These options only affect local development. When deployed to Vercel, the runtime ignores local settings and uses the Vercel world automatically.

Exporting a Function

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

next.config.ts

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;
}

withWorkflow

Usage

Monorepos and Workspace Imports

Options

Exporting a Function

On this page