Vercel's Workflow SDK published 5.0.1 and then kept cutting 4.8.x patches

Version 5.0.1 was published before 4.8.11 and 4.8.12

The three most recent releases form a sequence that needs explaining. `[email protected]` was published on 2026-10-01 at 20:55. `[email protected]` followed the same day at 23:23, about two and a half hours later. `[email protected]` came on 2026-10-02 at 23:19, roughly a day after that. The last recorded push to the repository is 2026-10-03, so all three arrived within about three days of each other, and the highest major version is not the newest one. That is what parallel maintenance lines look like in practice: a 4.x branch receiving fixes while 5.x exists, or a 5.0.1 that was cut and then found wanting. Nothing in the documentation says which, because the file never mentions the 4.8 line at all. Nor does the quick start pin a major version, so a reader following it verbatim installs whatever the tag of the day resolves to. For a consumer the effect is concrete. A dependency on `^5` and a dependency on `^4` resolve to different code, move at different speeds, and are not covered by the same fixes. The README gives no upgrade note, no compatibility table and no statement about which line is the one to use.

A Rust compiler plugin sits inside the TypeScript workspace

The repository is described as a TypeScript project, and the root does hold `pnpm-workspace.yaml`, `turbo.json` and a large `packages/` tree. It also holds `Cargo.toml` and `Cargo.lock`, which declare a Cargo workspace of their own with exactly two members: `packages/swc-plugin-workflow` and a wasm target under the workbench's swc-playground. The workspace pins the Rust side to edition 2024 and rust-version 1.87, with a single author, Pranay Prakash, and the same Apache-2.0 licence as the JavaScript side. Three settings in the release profile describe a binary being made as small as possible: `lto = true`, `opt-level = "s"` under a comment about optimising for size, and `strip = "symbols"` under a comment about stripping debug symbols, with `codegen-units = 1` to keep it all in one unit. One detail is worth noting for anyone tracking versions: `publish = false` and a workspace version of `0.1.0`. The Rust crates are never published and carry a placeholder version that will never line up with the npm versions at 4.8.x and 5.0.x.

The event log keeps its own race reproduction script

The root package.json tells you which failure modes the project has already hit. Two scripts are named after a condition rather than after a feature: `test:e2e:event-log-race-repro` runs `vitest run packages/core/e2e/event-log-race-repro.test.ts`, and `test:e2e:event-log-race-repro:local` runs a shell script under `scripts/` for the same reproduction driven locally. Keeping a reproduction for a race two years or one day after it was fixed is cheap and sensible; keeping two entry points for it suggests the condition is understood but not closed. The main end-to-end command is separate and does not include it. `test:e2e` names three files explicitly, the base suite, an agent suite and a dynamic-workflow suite, so any new end-to-end file has to be added to that command by hand rather than picked up by a glob. Two neighbouring scripts are just as specific: a staged Next.js and webpack check run through a Node script, and a benchmark run through a single vitest file under the same end-to-end directory. The granularity is unusual and it is the clearest signal in this file about what is hard to get right.

The docs ship inside the package so coding agents can read them

One note in the quick start does something unusual. It says the `workflow` package includes its full documentation, so coding agents can read version-matched guides locally from `node_modules/workflow/docs`. The emphasis is on version-matched: the copy a tool reads is the copy that matches the installed version, which removes the usual problem of an assistant describing an older API. The root listing shows how much of the repository is aimed at that audience. Alongside `docs/` there are `AGENTS.md`, `CLAUDE.md`, a `.claude/` directory, a `.cursor/` directory and a `skills/` directory, plus `.vscode/` and `.editorconfig`. Five separate surfaces carry instructions for tools that read files, in a project whose documentation is deliberately duplicated into a published tarball. That duplication is the cost of the design: the tree holds `docs/` as the source, the note says the package carries the result, and every release has to keep the two in step. The human-facing counterpart to the same local-first approach is the observability UI, opened by running the app in one terminal and the bundled web command in another.

Three places to run it, and one registry that is a JSON file

The Run anywhere section names three arrangements. Local development uses a bundled backend with no configuration. Deploying to Vercel gives managed storage, queuing, scaling, and observability. Self-hosting means using the Postgres backend or implementing a custom World, with the deployment page linked for the details. The first of those is the one that shapes everything else. A durability SDK whose default path needs no external service can be added to a project and run the same day, and that is what makes the quick start in this file four commands long. The third is the more interesting arrangement. A World is the extension point, and third-party Worlds are listed on a Worlds page described as maintainer-curated, covering both self-hosted and managed options. Submitting one is done by updating the Worlds Manifest, which is a JSON file in this repository. There is no registry service, no form and no automated listing. Adding a backend to the directory means opening a pull request against the SDK repository, and the listing depends on a maintainer merging it.

The Next.js integration is called with an empty object

The one framework example in the file is short. Wrapping the config:

// next.config.ts
import { withWorkflow } from 'workflow/next';

export default withWorkflow({});

Nothing goes inside the braces, so every option is defaulted and the file shows none of them. Starting a run:

import { start } from 'workflow/api';
import { onboardUser } from './workflows/onboard-user';

await start(onboardUser, ['[email protected]']);

That call shape is worth pausing on. The first argument is an imported function rather than a workflow name or an identifier, so the entry point is a module you import, conventionally from a workflows directory. The second is a plain array of arguments. Nothing in the snippet sets a queue, a storage backend or a retry policy, which matches the promise that local development needs no configuration. Running it takes a second terminal:

npm run dev

npx workflow web

The file then points at getting-started guides for choosing a framework, rather than showing a second integration.

A pnpm workspace whose own documentation uses npm commands

The root package is named workflow-workspace, marked private, licensed Apache-2.0, and declares `node` as `^22.0.0 || ^24.0.0` with [email protected] as its package manager. Its scripts are turbo passthroughs: build runs `turbo build --filter='./packages/*'`, test runs `turbo test`, and clean and typecheck follow the same shape. The dependency list mixes two styles. Biome, vitest, its coverage and runner packages, esbuild and typescript are all requested through the catalog protocol, which means their versions live in one shared place in the workspace, while husky, lint-staged, turbo and the changesets packages carry explicit ranges. Changesets handles versioning, with `ci:version` running `changeset version` and `ci:publish` running the full build before `changeset publish`. What stands out is that the instructions a new user follows say `npm install workflow`, `npm run dev` and `npx workflow web`, while the repository itself is a pnpm workspace with a pnpm lockfile and turbo orchestration. Both are reasonable. The effect is that consuming the SDK and building it are two different toolchains.

Tarballs, a workbench, and a staged release path

Two root directories and one script describe how this project tests itself. There is a `workbench/` tree, a `tarballs/` directory, and a script named for staging the workbench with tarballs. Running the workbench against packed tarballs rather than against the source tree is how you catch packaging problems, such as a file that is present in the repository but missing from what gets published, and it is the same concern that produces the documentation note about version-matched guides inside the package. The `tarballs/` directory sits in the repository root rather than under a build output folder, so it is a working directory someone chose rather than something the toolchain created. Release notes are generated by another script, and the publish path rebuilds before it publishes instead of shipping a prebuilt artifact. Alongside them the root carries `DCO.txt`, a code of conduct, a licence file and a security section that asks for vulnerabilities to be disclosed by email to a responsible disclosure address under an open source bug bounty programme, rather than filed as a public issue. The dependency list in the root file is cut off partway through a lint-staged entry, so what follows it is not visible.

Editorial conclusion

Workflow SDK suits a TypeScript codebase that wants durable functions, retries and a local observability view without standing up storage, and the bundled backend is what makes the quick start genuinely quick. Check two things before pinning a version: the 4.8 and 5.0 lines were both being published in the same window, so decide which line you track, and read the framework guide rather than the one Next.js snippet, since the quick start calls the integration with an empty object and shows none of the available options. If you need storage outside Vercel, the self-hosted path is the Postgres backend or a World you implement, and listing your own World means editing a JSON file in the SDK repository.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. vercel/workflow on GitHub