---
title: Build and Diagnostics
description: Build-time environment variables for manifests, source maps, and development diagnostics.
type: reference
summary: Configure generated bundles and build-time diagnostics.
related:
  - /docs/configuration/framework-options
  - /docs/api-reference/workflow-next/with-workflow
---

# 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`](/docs/api-reference/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 `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.


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)