What's new in v5?

We recommend upgrading to v5 to get all of the performance, cost, and feature improvements listed below. Install the migration skill, then tell your agent to migrate your app from Workflow SDK v4 to v5.

npm install workflow@latest
npx skills add https://github.com/vercel/workflow --skill migrating-workflow-v4-to-v5

Highlights

Faster and cheaper runs

The largest change in v5 has no API surface: the runtime does far less work per unit of progress. The time between calling start() and your first step body executing is now less than half of what it was in v4. This is made possible by many smaller optimizations:

A workflow invocation now does as much as it can in a single pass. In 4.x, progress was largely deferred to the queue: an invocation would execute a step, hand back to the queue, and let a fresh invocation pick up the next one. v5 creates and executes several steps inline per suspension, in parallel, and only uses the queue for a wait, a hook, or when the function approaches its timeout.

The runtime avoids waiting on the persistence layer where it can determine that it is safe for your workload. The runtime skips many API calls when they aren't needed, such as requesting the event log on a run's first invocation. Step creation is folded into step execution rather than being its own round trip. The inline loop consumes the event-log delta from the previous step's write instead of re-listing events. Each optimization is gated on specific runtime conditions and can be turned off individually. See Runtime tuning.

The workflow VM is kept alive across inline steps. Within one invocation, a step- or attribute-driven suspension keeps the live VM and hydrated state, including when hooks or waits are open or created at the same boundary, so the next iteration appends only the newly written events instead of rebuilding the sandbox and replaying the whole log. Step inputs made of plain data or standard built-ins keep this fast path; see WORKFLOW_RETAINED_VM.

Replay no longer downloads recorded step inputs. Replay recomputes step arguments by re-running workflow code, so it reads the event log without the input of each step. For workflows that pass growing state into their steps, this removes the part of the replay transfer that grew quadratically with the run. Worlds opt in through resolveData: 'skip-step-inputs', and Vercel Workflows supports it.

Resuming a hook takes one round trip instead of two. resumeHook() writes the hook_received event and dispatches the queue message concurrently, with a (runId, resumeId) dedup constraint keeping the two writers converging on exactly one event. See Resilient hook resumption.

A suspension's writes go out as one batch. The step_created and wait_created events a suspension produces are folded into a single durable write with a per-event outcome, instead of one request each, and a fan-out's inline step bodies start straight off that commit rather than each claiming its step first. This engages on Worlds that implement the batch API and can be turned off with WORKFLOW_BATCH_TRANSITIONS=0. See Batched event writes.

Concurrent writers no longer compete for a position in the log. Each event's position used to be claimed by the write that filled it, so a wide fan-out serialized on that claim. Positions are now handed out ahead of the commit, which is what makes the fan-out above cheap. The cost is a position whose writer dies, which the backend closes with a noop event that replay steps over. Nothing about this is visible from workflow code; WORKFLOW_SEALED_LOG=0 is the kill switch, and existing runs keep the scheme they were created on.

Payloads are compressed before they are encrypted and sent to the API. Repetitive payloads compress heavily; AI token streams average around 80% smaller. That is less stored data and less to move over the network.

On Vercel Workflows these benefits compound to reduce compute costs by up to 80% for workflows made of many small steps, and storage cost by up to 70%, depending on the workload. Depending on your setup, you may see similar gains using self-hosted or third-party Worlds.

How much work fits in one invocation now scales with the function's own limit: the inline budget is derived from the runtime deadline the World reports, so raising maxDuration widens it without configuration. See WORKFLOW_V2_TIMEOUT_MS.

Benchmarks on Vercel compare v5.2.0 with v4.8.12:

See Performance for how these benchmarks are measured, the full results, and their limits.

Multi-region support

Workflow run IDs are now tagged with the compute region they were created in, or the region specified when calling start(). Worlds can use this to pin execution to that region. This is now the default when deploying to Vercel, and run data will automatically be co-located with the compute region that the run was started in.

See Multi-region on the Vercel World for how automatic pinning works and how to select a region explicitly, and Building a World for adding regional placement to a custom World.

Inflight cancellation

AbortController and AbortSignal are now serializable, and signals can be passed into steps, so a workflow can abandon in-flight work without waiting for a step to finish.

import { sleep } from "workflow";

export async function raceWithTimeout() {
  "use workflow";

  const controller = new AbortController();

  const result = await Promise.race([
    fetchData(controller.signal),
    sleep("10s").then(() => null),
  ]);

  if (result === null) {
    controller.abort();
  }

  return result;
}

async function fetchData(signal: AbortSignal) {
  "use step";
  const response = await fetch("https://api.example.com/data", { signal });
  return response.json();
}

The abort reaches a step that is already executing, not just the next one to start, so a fetch() in flight when the controller aborts is torn down. Cancellation stays cooperative: a step that ignores its signal still runs to completion.

Cancelling from the outside gained detail too: run.cancel() accepts a cancelReason, recorded on the cancellation event and shown in the run detail view. And cancellation now works in bulk: workflow cancel takes --status pending|running and --workflowName to cancel a batch in one operation, and the runs table in the web UI cancels every selected run in a single request. See CLI and web UI.

See Cancellation, How cancellation works, and the in-flight cancellation changelog.

Run attributes

Attach string metadata to a run with setAttributes(), or seed it at creation with the attributes option of start(), then search and filter runs by key=value. Attributes were available in beta and are generally available in v5 under their final names: the experimental_setAttributes alias is gone.

Some attributes are set for you: a run started from inside another workflow or step is automatically tagged with the reserved $parentRunId and $rootRunId attributes, so a whole chain or fan-out of related runs can be found with a single attribute filter.

Vercel Observability can search runs by attribute. workflow inspect and the local web UI read them from world.analytics on any World that implements it.

See Attributes.

Richer serialization

Everything that crosses a workflow/step boundary is serialized. In v5, built-in errors such as TypeError preserve their type, message, stack, and cause chain through WorkflowRunFailedError.cause. Plain user-defined Error subclasses preserve their name but revive as generic errors unless they implement custom serialization. Bundled module copies can still have distinct constructors, so use SDK error .is() helpers instead of instanceof:

import { FatalError } from "workflow";
import { WorkflowRunFailedError } from "workflow/errors";
import { getRun } from "workflow/api";

try {
  await getRun(runId).returnValue;
} catch (error) {
  if (
    WorkflowRunFailedError.is(error) &&
    FatalError.is(error.cause) 
  ) {
    console.error(error.errorCode, error.cause.message);
  }
}

Workflow function references and Run handles are serializable too, so a step can receive a workflow function to start() or a run handle to await. And when a value cannot cross a boundary, the failure is precise instead of generic: dedicated SerializationError and structured context-violation errors name the offending value and where it was used.

See Serialization.

A redesigned trace viewer

The trace viewer has been rebuilt with a visible timeline, a minimap, pan, zoom, debug functionality, a new JSON viewer, keyboard navigation, and more.

Vercel Observability uses this trace viewer for all runs, v4 included, but with v5, you get the same new design for self-hosted UI and local debugging. See Observability.

The local tooling around it grew as well: on Nitro the dev server has the web UI built in at /_workflow, workflow inspect runs accepts --since/--until listing windows, run lookups by name search past the backend's default 24-hour window, and Worlds can surface their own run fields in inspect output. For example, the Vercel World shows each run's region. On any other framework, createWorkflowWebHandler() from @workflow/web/handler serves the same UI as one Request to Response handler under a base path of your choosing.

Each run also carries more of the infrastructure it ran on. A step attempt records the compute instance that executed it, surfaced as Compute Instance ID in the run sidebar and as a faas.instance span attribute on flow and step spans, so a run that behaves oddly can be correlated with one warm instance. The sidebar also shows a copyable Request ID for looking the invocation up in your platform's logs.

Custom hook token retention

A Hook token is normally reserved only while its workflow is running. Pass experimental_minRetention to createHook() to keep the token unavailable for at least a given duration after the Hook is created, so a duplicate request arriving after the original run finished still collides instead of starting fresh work. This allows for durable run idempotency with custom durations.

All three first-party Worlds now implement it: Vercel accepts up to 30 days, and the Local and Postgres Worlds default to the same ceiling (see WORKFLOW_LOCAL_HOOK_RETENTION_LIMIT_DAYS and its Postgres equivalent). A retained Hook remains readable with getHookByToken() after its run ends, but cannot be resumed.

Also new in 5.0

• start() from inside a workflow. Spawn a child run or hand off to a new run directly in a workflow function, without wrapping it in a step. See Starting workflows.
• Hook token takeover. Pass experimental_force: true to createHook() when the newest run should own a token another run still holds. The previous owner is woken and its await hook rejects with HookForceClaimedError, while resumeHook() callers, including one already in flight, are routed to the new owner without noticing. Supported by all three first-party Worlds.
• Stronger hook coordination. hook.getConflict() resolves with the conflicting Run rather than a bare { runId }, so a duplicate can await conflict.status, await conflict.returnValue, or await conflict.cancel() directly. See Run idempotency.
• Support for more frameworks. React Router (v7 and v8, via Nitro) and NestJS are now supported.
• A misrouted delivery no longer fails a run. Runs are pinned to the deployment that created them. A delivery that arrives at a different deployment is now re-routed to the pinned one with backoff instead of failing, and only gives up with the new DEPLOYMENT_MISMATCH error once the recovery budget is spent. Nothing executes on the wrong deployment while this happens. In 4.x the same situation surfaced as an unexplained decryption failure.
• A run cannot be forked across environments. start() stamps the environment it was called from onto the queue message, and a deployment refuses a delivery whose run was created in a different environment. Previously a preview client and a production deployment could each hold half of one run ID.
• An experimental QuickJS VM engine. Set WORKFLOW_VM=quickjs to run workflow functions in a QuickJS VM compiled to WebAssembly instead of node:vm, for platforms that do not provide node:vm. Replay semantics are identical, but the available globals are not: check the differences before switching an existing deployment. By default, an encrypted QuickJS run that passes 1,000 events resumes from a VM-memory snapshot instead of replaying its full event log (see WORKFLOW_SNAPSHOT_THRESHOLD).
• Experimental dynamic workflows. Pass workflow source as a string to start() to run orchestration assembled after deployment over steps already deployed with your app. The code is stored with the run (encrypted on Vercel), so replays always execute the code the run started with. Off unless the deployment sets WORKFLOW_EXPERIMENTAL_DYNAMIC_WORKFLOWS=1. See Dynamic Workflows.
• A WebSocket transport for event and stream writes on the Vercel World, which sends a run's event writes and stream writes over a socket instead of one HTTP request each. It is the default; set WORKFLOW_EVENTS_TRANSPORT=http or WORKFLOW_STREAMS_TRANSPORT=http to opt out. Tracing is unaffected: each write still emits an http POST client span, synthesized around the frame, with the transport on workflow.events.transport.
• await run.returnValue waits instead of polling. Reading a run's result long-polls the World until the run reaches a terminal status, rather than asking again on a fixed interval. A result is observed as soon as it exists, and an idle wait costs one open request instead of a request per tick. Worlds that do not implement the long poll keep the interval.
• An event arriving mid-replay no longer fails the run. A hook resume or step completion landing while a replay is in flight used to be able to fail it with CORRUPTED_EVENT_LOG. Writes now come back with the events the replay had not seen, and the event is held for whichever part of the workflow awaits it. A run only fails when the log is genuinely missing a position.

Breaking changes

Application code

Runs created on 4.x keep executing on the deployment that created them, so upgrading a deployment does not migrate in-flight runs. One storage caveat is worth knowing about: failed runs stored by @workflow/world-postgres before the upgrade read back with error: undefined, because the payload lives in the legacy error text column rather than errorJson.

If you maintain a World

The World interface, which defines the storage, queue, streaming, and analytics contract that a Workflow SDK deployment runs against, also changed in v5. Those changes are not visible from application code. If you implement World yourself or maintain a build integration that compiles workflow files, upgrade it alongside the SDK. See Upgrading a World to v5 for the full interface delta and the contract changes that affect existing implementations. There is a separate skill for that job because none of it applies to application code:

npx skills add https://github.com/vercel/workflow --skill migrating-world-v4-to-v5

Applications on the Vercel, Local, and Postgres Worlds need nothing from that page: those implementations ship with the SDK and are already on the v5 spec.