workflow 5.0.0-beta.3 → 5.0.0-beta.30

package/docs/configuration/framework-options.mdx

@@ -0,0 +1,165 @@
+---
+title: Framework Options
+description: Build-time and dev-server configuration for Workflow framework integrations.
+type: reference
+summary: Configure Workflow through framework plugins and module options.
+related:
+  - /docs/api-reference/workflow-next/with-workflow
+  - /docs/configuration/build-and-diagnostics
+---
+
+Framework options are read at build or dev-server startup. Use them for settings that belong in source control, such as source-map behavior or framework-specific output paths.
+
+## Next.js
+
+`withWorkflow()` accepts an optional second argument.
+
+### `workflows.local.port`
+
+- Environment override: `PORT`
+- Default: auto-detected
+- Local-only. Sets the application port used by the Local World when queue messages call back into the app.
+- The option writes `PORT` for non-Vercel builds.
+
+### `workflows.sourcemap`
+
+- Environment override: `WORKFLOW_SOURCEMAP`
+- Default: `inline` in development, `false` in production
+- Controls source maps for generated workflow bundles.
+- Explicit config wins over `WORKFLOW_SOURCEMAP`.
+
+```typescript title="next.config.ts" lineNumbers
+import { withWorkflow } from "workflow/next";
+
+export default withWorkflow(
+  {},
+  {
+    workflows: {
+      local: {
+        port: 4000,
+      },
+      sourcemap: false,
+    },
+  }
+);
+```
+
+## Nitro and Nuxt
+
+Configure Workflow through the Nitro `workflow` module options.
+
+### `workflow.dirs`
+
+- Environment override: none
+- Default: `["workflows"]`
+- Directories scanned for workflow files.
+
+### `workflow.typescriptPlugin`
+
+- Environment override: none
+- Default: `false` for raw Nitro, `true` through the Nuxt module
+- Enables the Workflow TypeScript language-service plugin in generated `tsconfig.json`.
+- This affects editor diagnostics and completions. Workflow builds do not require it.
+- Raw Nitro leaves it opt-in because it changes TypeScript editor behavior. Nuxt enables it by default because the Nuxt module owns the generated `tsconfig.json` flow.
+
+### `workflow.runtime`
+
+- Environment override: none
+- Default: framework default
+- Node.js runtime emitted for Vercel Functions, such as `nodejs22.x` or `nodejs24.x`.
+
+### `workflow.sourcemap`
+
+- Environment override: `WORKFLOW_SOURCEMAP`
+- Default: `inline` in development, `false` in production
+- Controls source maps for generated workflow bundles.
+
+## NestJS
+
+Configure Workflow through `WorkflowModule.forRoot()`.
+
+### `workingDir`
+
+- Environment override: none
+- Default: `process.cwd()`
+- Application root used for workflow discovery and bundling.
+
+### `dirs`
+
+- Environment override: none
+- Default: `["src"]`
+- Directories scanned for workflow files.
+
+### `outDir`
+
+- Environment override: none
+- Default: `.nestjs/workflow`
+- Directory for generated workflow bundles.
+
+### `watch`
+
+- Environment override: none
+- Default: `false`
+- Rebuilds workflow bundles during development.
+
+### `moduleType`
+
+- Environment override: none
+- Default: `es6`
+- Set to `commonjs` when the Nest app compiles TypeScript to CJS through SWC.
+
+### `distDir`
+
+- Environment override: none
+- Default: `dist`
+- Compiled JavaScript output directory used by the CJS import rewrite.
+
+### `sourcemap`
+
+- Environment override: `WORKFLOW_SOURCEMAP`
+- Default: `inline` in development, `false` in production
+- Controls source maps for generated workflow bundles.
+
+### `skipBuild`
+
+- Environment override: none
+- Default: `false`
+- Skips bundle generation when bundles are already pre-built.
+
+## Astro
+
+### `sourcemap`
+
+- Environment override: `WORKFLOW_SOURCEMAP`
+- Default: `inline` in development, `false` in production
+- Controls source maps for generated workflow bundles.
+
+## SvelteKit
+
+### `sourcemap`
+
+- Environment override: `WORKFLOW_SOURCEMAP`
+- Default: `inline` in development, `false` in production
+- Controls source maps for generated workflow bundles.
+
+## Rollup
+
+### `exclude`
+
+- Environment override: none
+- Default: `[]`
+- Path prefixes skipped by the directive transform.
+
+## Source-map values
+
+`WORKFLOW_SOURCEMAP` accepts these 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.
+
+<Callout type="info">
+The legacy `WORKFLOW_EMIT_SOURCEMAPS_FOR_DEBUGGING=1` variable still works, but it only affects the final workflow wrapper and webhook bundle. Prefer `WORKFLOW_SOURCEMAP` or a framework `sourcemap` option.
+</Callout>

package/docs/configuration/index.mdx

@@ -0,0 +1,32 @@
+---
+title: Configuration
+description: Reference for Workflow SDK configuration options, environment variables, and CLI overrides.
+type: conceptual
+summary: Configure framework integrations, Worlds, runtime tuning, builds, and CLI observability.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/configuration/framework-options
+  - /docs/configuration/worlds
+  - /docs/configuration/runtime-tuning
+  - /docs/configuration/build-and-diagnostics
+  - /docs/configuration/cli-and-web-ui
+---
+
+Workflow SDK is configured through typed framework options, World factory options, environment variables, and CLI flags.
+
+When more than one surface controls the same setting, the usual precedence is:
+
+```txt
+explicit option or CLI flag > environment variable > built-in default
+```
+
+Invalid environment variable values do not crash the app. They log a warning and fall back to the default, or to the documented clamp range.
+
+## Configuration areas
+
+- [Framework options](/docs/configuration/framework-options) - build-time and dev-server options for Next.js, Nitro, NestJS, Astro, SvelteKit, and Rollup.
+- [Worlds](/docs/configuration/worlds) - `WORKFLOW_TARGET_WORLD`, Local World, Postgres World, and Vercel World configuration.
+- [Runtime tuning](/docs/configuration/runtime-tuning) - replay budgets, inline execution, queue delivery limits, compression, tracing, and advanced runtime escape hatches.
+- [Build and diagnostics](/docs/configuration/build-and-diagnostics) - public manifests, HMR logs, and source-map controls.
+- [CLI and web UI](/docs/configuration/cli-and-web-ui) - `workflow inspect`, `workflow web`, `workflow health`, and observability environment overrides.

package/docs/configuration/meta.json

@@ -0,0 +1,12 @@
+{
+  "title": "Configuration",
+  "pages": [
+    "index",
+    "framework-options",
+    "worlds",
+    "runtime-tuning",
+    "build-and-diagnostics",
+    "cli-and-web-ui"
+  ],
+  "defaultOpen": false
+}

package/docs/configuration/runtime-tuning.mdx

@@ -0,0 +1,156 @@
+---
+title: Runtime Tuning
+description: Runtime environment variables for replay, inline execution, queue delivery, compression, tracing, and advanced limits.
+type: reference
+summary: Tune Workflow runtime behavior where workflows execute.
+related:
+  - /docs/configuration/worlds
+  - /docs/how-it-works/event-sourcing
+---
+
+Runtime variables are read where workflows execute. Set them on the deployment or dev server.
+
+## Replay and queue delivery
+
+### `WORKFLOW_REPLAY_TIMEOUT_MS`
+
+- Default: `240000`
+- Clamp: `30000` to `780000`
+- Charged time budget for replay and orchestration work in one handler invocation.
+- Covers loading events, re-running the workflow function, resolving suspensions, and scheduling follow-up work.
+- Does not include time spent inside inline `"use step"` bodies. Steps are bounded by the platform function duration instead.
+
+For example, a workflow can run a 10-minute inline step even with `WORKFLOW_REPLAY_TIMEOUT_MS=300000`, because the replay budget is paused while the step body runs.
+
+### `WORKFLOW_REPLAY_TIMEOUT_MAX_RETRIES`
+
+- Default: `3`
+- Queue deliveries that may hit the replay timeout before the run is failed with `REPLAY_TIMEOUT`.
+
+### `WORKFLOW_MAX_QUEUE_DELIVERIES`
+
+- Default: `48`
+- Delivery attempts before a run or step is failed gracefully.
+- Can only be lowered. The default is calibrated so Workflow can record failure before the queue expires the message.
+
+### `WORKFLOW_REPLAY_DIVERGENCE_MAX_RETRIES`
+
+- Default: `3`
+- Recovery replays before replay divergence is recorded as corruption.
+
+## Inline execution
+
+### `WORKFLOW_V2_TIMEOUT_MS`
+
+- Default: `120000`
+- Wall-clock guard for the inline replay loop.
+- Once elapsed, the handler requeues the workflow instead of continuing to run more inline work in the same invocation.
+
+### `WORKFLOW_MAX_INLINE_STEPS`
+
+- Default: `3`
+- Clamp: `1` to `16`
+- Number of newly-created steps one invocation runs inline in parallel before queueing the rest.
+
+### `WORKFLOW_TURBO`
+
+- Default: enabled
+- Fast path for a run's first delivery.
+- Set `0` or `false` to disable.
+
+### `WORKFLOW_OPTIMISTIC_INLINE_START`
+
+- Default: disabled
+- Starts inline step bodies before their `step_started` event is confirmed.
+- Use only when step side effects are idempotent.
+- Set `0` or `false` to force it off, including the first-delivery fast path used by `WORKFLOW_TURBO`.
+
+### `WORKFLOW_INLINE_OWNERSHIP`
+
+- Default: enabled
+- Records which queue message owns each inline step execution, so a wake (hook resume, elapsed wait) that replays the run mid-step schedules a delayed backstop instead of immediately re-dispatching — and re-executing — the step. See [Inline step message ownership](/v5/docs/changelog/step-message-ownership).
+- Set `0` or `false` to revert to the previous unconditional immediate re-dispatch.
+
+### `WORKFLOW_INLINE_OWNERSHIP_LEASE_SECONDS`
+
+- Default: `860`
+- Clamp: `1` to `900`
+- How long after an inline step's latest `step_started` other invocations assume its owner may still be executing the body. Within the lease they defer the step's backstop message; past it they enqueue immediately.
+- Raise this on self-hosted multi-instance deployments whose inline steps run longer than the default (the default is sized for Vercel's function duration ceiling).
+
+## Compression and tracing
+
+### `WORKFLOW_DISABLE_COMPRESSION`
+
+- Default: compression enabled
+- Set `1` to disable compression when writing payloads.
+- Reads still decompress existing payloads.
+
+### `WORKFLOW_COMPRESSION_CODEC`
+
+- Default: automatic
+- Forces the write-side codec to `zstd` or `gzip`.
+- Invalid values are ignored. Automatic mode prefers `zstd` when the current Node.js runtime supports it, otherwise it falls back to `gzip`.
+
+### `WORKFLOW_TRACE_MODE`
+
+- Default: `linked`
+- OpenTelemetry span topology for runs.
+- Accepts `linked` or `continuous`.
+
+### `DEBUG`
+
+- Default: unset
+- Debug log filter with wildcards and negation.
+- Examples: `workflow:*`, `workflow:*,-workflow:telemetry:*`.
+
+## Queue namespace
+
+### `WORKFLOW_QUEUE_NAMESPACE`
+
+- Default: none
+- Queue topic namespace shared by build output and Worlds.
+- Must match `^[a-z][a-z0-9]*$`.
+- Set it consistently at build and runtime.
+
+## Streams and waits
+
+These variables are primarily for tests, debugging, or unusual deployments.
+
+### `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
+
+- Default: `10`
+- Stream write buffering interval.
+- Also available as `streamFlushIntervalMs` on Worlds that expose it.
+
+### `WORKFLOW_FRAMED_STREAM_MAX_RECONNECTS`
+
+- Default: `50`
+- Consecutive reconnect cap for framed stream readers.
+
+### `WORKFLOW_FRAMED_STREAM_MAX_TOTAL_RECONNECTS`
+
+- Default: `1000`
+- Total reconnect cap per stream session.
+
+### `WORKFLOW_WAIT_CONTINUATION_MAX_DELAY_SECONDS`
+
+- Default: `82800` (23 hours)
+- Longest single queue delay used for `sleep()` continuations.
+- If a wait is longer than this, Workflow queues one continuation for the maximum delay, then queues another continuation after that message fires, repeating until the wait's target time is reached.
+
+### `WORKFLOW_NEAR_ELAPSED_WAIT_THRESHOLD_SECONDS`
+
+- Default: `2`
+- Clock-skew tolerance for wait continuations that arrive near their target time.
+
+### `WORKFLOW_DEFERRED_CHECK_DELAY_MS`
+
+- Default: `100`
+- Delay before the unconsumed-event check fires.
+- Minimum: `10`.
+
+### `WORKFLOW_LOCK_POLL_INTERVAL_MS`
+
+- Default: `10`
+- Poll interval for detecting stream lock release.

package/docs/configuration/worlds.mdx

@@ -0,0 +1,228 @@
+---
+title: Worlds
+description: Configure the Workflow backend that stores runs and delivers queue messages.
+type: reference
+summary: Select and configure Local, Postgres, Vercel, or custom Worlds.
+related:
+  - /docs/deploying/world/local-world
+  - /docs/deploying/world/postgres-world
+  - /docs/deploying/world/vercel-world
+---
+
+A [World](/docs/deploying) stores workflow state and delivers queue messages.
+
+## Selecting a World
+
+### `WORKFLOW_TARGET_WORLD`
+
+- Surface: environment variable
+- Default: `local` outside Vercel; automatic Vercel World inside Vercel deployments
+- Selects a non-default World module.
+
+Outside Vercel, Workflow defaults to the Local World. On Vercel, leave `WORKFLOW_TARGET_WORLD` unset for the normal case; Workflow detects the Vercel deployment and selects the Vercel World automatically.
+
+Set `WORKFLOW_TARGET_WORLD` only when you want to use a custom or self-hosted World:
+
+- `local` - alias for `@workflow/world-local`.
+- `@workflow/world-postgres` - Postgres World package.
+- `./my-world.ts` - local module exporting a World, `createWorld()`, or a default factory.
+- Any package specifier - custom World package.
+
+The `vercel` alias exists for manual selection and tooling, but deployed Vercel apps do not need to set it.
+
+Export a configured World from a module when you need factory options instead of pure environment configuration:
+
+```typescript title="my-world.ts" lineNumbers
+import { createWorld } from "@workflow/world-postgres";
+
+export default createWorld({
+  connectionString: process.env.DATABASE_URL!,
+  jobPrefix: "myapp_",
+});
+```
+
+```bash title=".env"
+WORKFLOW_TARGET_WORLD="./my-world.ts"
+```
+
+## Local World
+
+The Local World is the default outside Vercel and is intended for development.
+
+### `dataDir`
+
+- Environment variable: `WORKFLOW_LOCAL_DATA_DIR`
+- Default: `.workflow-data`
+- Directory where runs, steps, events, hooks, streams, and the local manifest are written.
+
+### `baseUrl`
+
+- Environment variable: `WORKFLOW_LOCAL_BASE_URL`
+- Default: inferred from the app port
+- Full base URL used when queue messages call back into the app.
+- Overrides `port` and `PORT`.
+
+### `port`
+
+- Environment variable: `PORT`
+- Default: auto-detected
+- Local app port used to build the callback URL when `baseUrl` is unset.
+
+### `WORKFLOW_LOCAL_QUEUE_CONCURRENCY`
+
+- Factory option: none
+- Default: `1000`
+- Maximum number of concurrent local queue message handlers.
+
+### `WORKFLOW_LOCAL_QUEUE_MAX_VISIBILITY`
+
+- Factory option: none
+- Default: unlimited
+- Maximum seconds a local queue message stays hidden before the handler rechecks the run.
+
+### `recoverActiveRuns`
+
+- Environment variable: none
+- Default: `true`
+- Re-enqueues pending and running local runs when the World starts.
+
+### `tag`
+
+- Environment variable: none
+- Default: unset
+- Scopes local storage files to a tag, mainly for test isolation.
+
+### `streamFlushIntervalMs`
+
+- Environment variable fallback: `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
+- Default: `10`
+- Flush interval for buffered stream writes. The World option wins when set.
+
+## Postgres World
+
+The Postgres World is a self-hosted durable backend for long-running server processes.
+
+### `connectionString`
+
+- Environment variable: `WORKFLOW_POSTGRES_URL`, then `DATABASE_URL`
+- Default: `postgres://world:world@localhost:5432/world`
+- PostgreSQL connection string used by the runtime World.
+- The `bootstrap` migration command uses the same precedence.
+
+### `pool`
+
+- Environment variable: none
+- Default: new `pg.Pool`
+- Existing `pg.Pool` to use instead of constructing one from `connectionString`.
+
+### `jobPrefix`
+
+- Environment variable: `WORKFLOW_POSTGRES_JOB_PREFIX`
+- Default: `workflow_`
+- Prefix for Graphile Worker job names.
+
+### `queueConcurrency`
+
+- Environment variable: `WORKFLOW_POSTGRES_WORKER_CONCURRENCY`
+- Default: `50`
+- Number of concurrent workers polling for jobs.
+- Also bounds concurrent parent-to-child workflow return-value polls.
+
+### `maxPoolSize`
+
+- Environment variable: `WORKFLOW_POSTGRES_MAX_POOL_SIZE`
+- Default: `pg` default
+- Maximum size of the internal `pg.Pool` when the World creates the pool.
+
+### `namespace`
+
+- Environment variable fallback: `WORKFLOW_QUEUE_NAMESPACE`
+- Default: none
+- Queue topic namespace. For example, `custom` changes `__wkf_*` topics to `__custom_wkf_*`.
+
+### `streamFlushIntervalMs`
+
+- Environment variable fallback: `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
+- Default: `10`
+- Flush interval for buffered stream writes. The World option wins when set.
+
+## Vercel World
+
+The Vercel World is configured automatically inside Vercel deployments. The platform provides the deployment ID, project ID, request authentication, queue integration, storage, and encryption material.
+
+Most applications should not set `WORKFLOW_VERCEL_*` variables on Vercel. They configure tooling that talks to a Vercel Workflow project from outside a deployment, such as the `workflow` CLI, the web UI, CI, or tests. The runtime warns if these variables are set in a deployed Vercel function because they do not control runtime configuration there.
+
+Platform-provided values such as `VERCEL_DEPLOYMENT_ID`, `VERCEL_PROJECT_ID`, and `VERCEL_DEPLOYMENT_KEY` are read by the runtime inside Vercel deployments. Do not set them yourself.
+
+### `token`
+
+- Environment variable: `WORKFLOW_VERCEL_AUTH_TOKEN`, then `VERCEL_TOKEN`, then Vercel CLI login
+- CLI flag: `--authToken`
+- Default: inferred when possible
+- Vercel API token for external tooling. Keep it secret.
+
+### `projectConfig.environment`
+
+- Environment variable: `WORKFLOW_VERCEL_ENV`
+- CLI flag: `--env` or `-e`
+- Default: `production`
+- Vercel environment targeted by tooling. Accepts `production` or `preview`.
+
+### `projectConfig.projectId`
+
+- Environment variable: `WORKFLOW_VERCEL_PROJECT`
+- CLI flag: `--project`
+- Default: inferred from `.vercel/project.json` when possible
+- Vercel project ID.
+
+### `projectConfig.teamId`
+
+- Environment variable: `WORKFLOW_VERCEL_TEAM`
+- CLI flag: `--team`
+- Default: inferred from `.vercel/project.json` when possible
+- Vercel team ID.
+
+### `WORKFLOW_VERCEL_PROJECT_NAME`
+
+- Factory option: none
+- CLI flag: none
+- Default: inferred when possible
+- Project slug used for dashboard links.
+
+### `WORKFLOW_VERCEL_BACKEND_URL`
+
+- Factory option: none
+- CLI flag: none
+- Default: `https://api.vercel.com/v1/workflow`
+- Workflow API proxy URL for external tooling.
+
+### `VERCEL_WORKFLOW_SERVER_URL`
+
+- Factory option: none
+- CLI flag: none
+- Default: unset
+- Direct workflow-server URL override for testing or custom infrastructure. Normal deployments do not need it.
+
+### `VERCEL_QUEUE_MAX_DELAY_SECONDS`
+
+- Factory option: none
+- CLI flag: none
+- Default: `82800` (23 hours)
+- Maximum delay for one Vercel Queues continuation message when implementing `sleep()`.
+- Longer sleeps schedule another continuation when the first one fires.
+
+`VERCEL_QUEUE_MAX_DELAY_SECONDS` defaults to 23 hours because Vercel Queues message delays are capped by the message TTL, and the default TTL is 24 hours. Workflow stays inside that default and chains continuation messages for longer sleeps.
+
+### `WORKFLOW_REQUEST_TIMEOUT_MS`
+
+- Factory option: none
+- CLI flag: none
+- Default: `60000`
+- Per-request timeout for Vercel World HTTP calls to workflow-server.
+
+### `WORKFLOW_MAX_CHUNKS_PER_REQUEST`
+
+- Factory option: none
+- CLI flag: none
+- Default: `1000`
+- Maximum stream chunks written in one Vercel World request. Larger batches are split.