Build and Diagnostics

Build and diagnostics variables are read by the compiler, builders, and framework integrations when your app is built or when the dev server starts.

Source maps

`WORKFLOW_SOURCEMAP`

Framework option: sourcemap where supported
Default: inline in development, false in production
Controls source maps for generated workflow bundles.
Explicit framework config wins over this environment variable.

Accepted values:

true, inline, or 1 - append an inline base64 source map to each generated bundle.
linked - write a .map file and add a sourceMappingURL comment.
external - write a .map file without adding the comment.
both - emit inline and external source maps.
false or 0 - omit source maps.

`WORKFLOW_EMIT_SOURCEMAPS_FOR_DEBUGGING`

Default: disabled
Legacy source-map toggle kept for compatibility.
Only affects the final workflow wrapper and webhook bundle.
Prefer WORKFLOW_SOURCEMAP or a framework sourcemap option.

Manifests

`WORKFLOW_PUBLIC_MANIFEST`

Default: disabled
Set 1 to expose the workflow manifest at /.well-known/workflow/v1/manifest.json.
Useful for end-to-end tests and tools that need to discover workflows over HTTP.

Discovery

`WORKFLOW_DISCOVER_NODE_MODULES`

Framework option: discoverWorkflowsInNodeModules where supported
Default: enabled
Controls whether workflow discovery descends into node_modules. By default, dependencies that declare a workflow/@workflow/* dependency can ship "use workflow"/"use step" files that are discovered and compiled into your app's bundles.
Set 0 or false to opt out: imports from your application code that resolve into node_modules are not followed, so the build never reads, scans, or descends into dependency file graphs. This skips the cost of scanning node_modules and stops third-party workflow/step/serde code from being discovered. Useful when a dependency ships workflow code you don't want compiled into your app, or trips discovery with directive strings you don't intend to run.
The SDK's own runtime serde classes (for example, Run) stay registered because they are reached through a seeded entry point, and imports within node_modules are still followed.
Explicit framework config wins over this environment variable.

Testing

`WORKFLOW_VITEST_VERSION_CHECK`

Default: enabled
Read by @workflow/vitest in globalSetup, once per test run.
The plugin builds and runs your workflows against the copy of @workflow/core it was installed with. Before building, it compares that copy with the one your app resolves: a different major fails the run with the install command that fixes it, and any other difference logs a warning.
Set off (or 0 / false) to skip the check, for example in a setup that resolves two copies on purpose.

Development diagnostics

`WORKFLOW_DEV_HMR_LOGS`

Default: disabled
Set 1 to log workflow rebuild activity during next dev.
Useful for diagnosing watch and hot module replacement (HMR) issues.

`WORKFLOW_DEV_WATCH_IGNORED_PATHS`

Default: unset
Dev-mode only (next dev). Comma-separated list of path fragments the file watcher should never watch, in addition to the built-in ignores and your project's .gitignore.
Each entry is matched as a substring of the absolute path (for example, /fixtures/,/generated/).
The watcher already respects .gitignore (walking from the app directory up to the workspace root). Use this variable only for large directories you cannot or do not want to add to .gitignore.

What the dev watcher tracks

In next dev, Workflow watches the modules your app actually imports, not your whole project:

Every file the workflow build reached from your Next.js entrypoints. Editing one rebuilds the affected workflow bundles.
The directories those files live in, so a module you add under an import you have already written is picked up.
The paths behind imports that do not resolve yet. Write import './billing/workflow' before creating the file, or delete a workflow module and restore it, and the module is bundled as soon as it exists, wherever it lives.
The app and pages directories (src/ variants included), so a route you create is noticed even though nothing imports it yet, along with root entrypoints such as middleware.ts and instrumentation.ts.

A directory your app never imports is not watched at all, so files there never produce workflow bundles or rebuilds. Import one from a page and the next rebuild brings it into the watched set. Files are only ever watched through the directory that contains them, so the watcher's cost scales with the number of watched directories rather than the number of source files.