withWorkflow

Configures webpack and Turbopack loaders to transform workflow code ("use step" and "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";
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

By default, Next.js detects the correct workspace root automatically. If your Next.js app lives in a subdirectory such as apps/web and workspace resolution is not working correctly, you can set outputFileTracingRoot as a workaround:

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

Options

withWorkflow accepts an optional second argument to configure the Next.js integration.

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

const nextConfig: NextConfig = {};

export default withWorkflow(nextConfig, {
  workflows: {
    local: {
      port: 4000,
    },
    sourcemap: false,
  },
});

Source maps

The step bundle and intermediate workflow bundle default to 'inline' source maps in development (so stack traces from step errors and workflow virtual machine (VM) errors point at your source files) and to false in production, so function bundles stay small. The sourcemap option lets you change that:

In production, source maps are already off by default. Setting sourcemap: false explicitly also turns them off in development, and it drops the inline source map from every bundle while skipping the source-map-support runtime shim on the Vercel step function (the same behavior production gets by default), the main lever for staying under the Vercel 250 MB function size limit. The tradeoff is that workflow VM stack traces will reference generated code (for example, evalmachine.<anonymous>) rather than your source files.

The option can also be set via the WORKFLOW_SOURCEMAP environment variable, which accepts the same values plus '0' / '1' as aliases for false / true. Precedence is: explicit config > WORKFLOW_SOURCEMAP > the environment-aware default ('inline' in development, false in production). Development is detected from next dev / NODE_ENV=development, so the config option and the env var both let you force either behavior in either environment.

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.

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