Cloudflare vitest-plugin v1: the migration guide targets 0.16.0, the last old release was 0.22.0

Summary. On 19 August 2026 Cloudflare announced that @cloudflare/vitest-pool-workers is now @cloudflare/vitest-plugin. The package hit npm as version 1.0.0 on 20 August 2026 at 17:42 UTC. The claim that the API is unchanged holds up: the shipped TypeScript definition files for @cloudflare/vitest-pool-workers@0.22.0 and @cloudflare/vitest-plugin@1.0.0 are 31,322 and 31,316 bytes and differ on exactly one line, a documentation comment naming the config subpath. Everything around that clean rename is less tidy. Cloudflare's own migration guide tells you to replace "@cloudflare/vitest-pool-workers": "^0.16.0", a version published on 5 May 2026, while the final release of the old package is 0.22.0 from 18 August 2026, six minor versions later. The old package carries no npm deprecation notice, so npm outdated and CI tell your team nothing. The codemod you are told to run, @cloudflare/codemods, is at 0.1.0 and was first published on 20 August 2026, eight minutes before the package it migrates you to. And outbound request mocking, the one part of a Workers test suite most likely to break, now routes through @msw/cloudflare, a third-party package at version 0.0.1 with two published versions, no GitHub releases, and a last commit dated 7 July 2026. Teams on the Workers Paid plan, minimum $5 USD per month per account, should treat this as a half-day of test-suite work, not a find-and-replace.

What actually changed on 19 and 20 August 2026

The changelog entry, dated 19 August 2026, is three sentences long. It states that version 1 of the Workers Vitest integration is published as @cloudflare/vitest-plugin, that the Vitest configuration API is unchanged, and that existing projects must update the dependency name, package imports, and TypeScript types entries.

That list of three is the problem. It is accurate for the package itself and incomplete for the test suite.

The npm registry gives the timeline precisely. @cloudflare/vitest-plugin was created on 20 August 2026 at 14:33 UTC as a 0.0.0 placeholder and republished as 1.0.0 at 17:42 UTC the same day. The changelog carries datePublished and dateModified of 2026-08-19. For roughly a day, the announcement pointed at a package name that resolved to a stub.

Meanwhile @cloudflare/vitest-pool-workers has 321 published versions going back to 14 March 2024. Its last release, 0.22.0, landed on 18 August 2026, one day before the rename was announced.

The rename really is API-clean, and that is checkable

Cloudflare's strongest claim survives inspection. Both packages ship a single ambient declaration file at types/cloudflare-test.d.ts. Fetched from jsDelivr and compared, the two files differ on line 184 only, where a comment reads @cloudflare/vitest-pool-workers/config in the old file and @cloudflare/vitest-plugin/config in the new one. Nothing else moved.

The cloudflare:test module still exports the same surface in 1.0.0: env, SELF, createExecutionContext, waitOnExecutionContext, runInDurableObject, runDurableObjectAlarm, evictDurableObject, listDurableObjectIds, abortAllDurableObjects, evictAllDurableObjects, createScheduledController, createMessageBatch, getQueueResult, applyD1Migrations, adminSecretsStore, introspectWorkflow, introspectWorkflowInstance and createPagesEventContext.

So if your tests only call those, the codemod genuinely is the whole job.

Gap one: the migration diff points at a version from May

The manual migration section of Cloudflare's guide shows this diff:

- "@cloudflare/vitest-pool-workers": "^0.16.0"
+ "@cloudflare/vitest-plugin": "^1.0.0"

Version 0.16.0 was published on 5 May 2026. After it came 0.16.5 on 14 May, 0.17.0 on 30 June, 0.18.0 on 2 July, 0.19.0 on 28 July, 0.20.0 on 31 July, 0.21.0 on 10 August and 0.22.0 on 18 August 2026.

This matters because of how npm treats a caret on a 0.x version. ^0.16.0 permits 0.16.x and nothing above it. A team that has kept current has "^0.22.0" in package.json, and the string in Cloudflare's diff does not appear in their file at all. The guide is not wrong about the intent, but anyone copying it literally, or handing it to an agent to apply, finds no match and may conclude the dependency is not present.

Gap two: npm gives no signal at all

@cloudflare/vitest-pool-workers@0.22.0 carries no deprecated field in its registry metadata as of 23 August 2026. There is no npm deprecation warning on install, nothing for npm outdated to flag, and no CI failure.

The rename exists in a changelog post and in the docs. It does not exist in the package manager, which is where most teams would expect to meet it. A repository that nobody touches for three months will keep installing the old package, resolving cleanly, and passing CI, while the documentation it points at describes a package it does not have.

If you run a fleet of Workers repositories, the practical detection is a grep across lockfiles rather than a dependency-audit tool. The same pattern shows up elsewhere in the npm supply chain, where publishing-side metadata and install-side signals diverge; we covered a related case in npm provenance attestations and the cooldown policy.

Gap three: the codemod is younger than the thing it migrates

Cloudflare's docs give one command:

npx @cloudflare/codemods vitest:pool-workers-to-vitest-plugin

@cloudflare/codemods was created on npm on 20 August 2026 at 17:28 UTC and published 0.1.0 at 17:34 UTC. The package it migrates you to, @cloudflare/vitest-plugin@1.0.0, went up eight minutes later at 17:42 UTC. There are two versions in total and the package declares no dependencies.

The guide does document two flags worth using: --dry-run previews the changes, and --files <glob> limits the files touched. On a monorepo, run both. A 0.1.0 codemod rewriting package.json, imports and tsconfig.json across dozens of packages is not something to run unreviewed on a Friday.

There is also a smaller contradiction inside the docs on the exact thing the codemod fixes. Cloudflare's "Write your first test" page, last updated 20 August 2026, says in prose to add "@cloudflare/vitest-plugin" to your types array, while the code block immediately below it uses "@cloudflare/vitest-plugin/types". The migration guide's diff also uses the /types subpath. The bare package name in the prose is the odd one out.

Gap four: outbound mocking is the real migration, and it predates the rename

This is the part that will cost your team time, and the changelog does not mention it.

Cloudflare's "Mock outbound requests" page, last updated 20 August 2026, now tells you to install msw and @msw/cloudflare, create a setupNetwork() mock, and wire network.enable(), network.resetHandlers() and network.disable() into beforeAll, afterEach and afterAll in a Vitest setup file, then add that file to your setupFiles array.

Adding an entry to setupFiles is a change to the Vitest configuration. The changelog says the Vitest configuration API is unchanged. Both statements can be true at once, because the API did not change while your config file does. That distinction is easy to miss when the announcement lists exactly three things to update.

The older fetchMock helper is gone, and it did not go in v1. Checking the shipped type definitions of @cloudflare/vitest-pool-workers at 0.16.0, 0.18.0, 0.20.0, 0.21.0 and 0.22.0, and of @cloudflare/vitest-plugin@1.0.0, the string fetchMock appears zero times in all six. It is also absent from the entire workers/llms.txt documentation index. The undici MockAgent class is still declared in the ambient types at line 839 of both files, but no documented cloudflare:test export hands you one.

So the mocking rewrite landed sometime before 5 May 2026. The rename is simply the moment most teams will notice, because the new docs point somewhere new.

The dependency that deserves a second look

@msw/cloudflare is published by Artem Zakharchenko, the maintainer of Mock Service Worker, and it is MIT licensed in its package.json. It is also very early software.

As of 23 August 2026 the npm registry shows version 0.0.1, published 30 June 2026, with two versions ever. The mswjs/cloudflare repository was created on 22 April 2026, has 95 stars, zero GitHub releases, and its most recent commit is dated 7 July 2026 with the message "chore: pin missed action, separate job permissions". There is no LICENSE file in the repository root, though package.json declares MIT. The repository is not archived and has zero open issues.

None of that makes it bad code. It makes it a 0.0.1 dependency sitting on the documented path of a 1.0.0 release from Cloudflare, which is a different risk conversation than the version numbers suggest.

There is a version-floor detail to check too. Cloudflare's page says to install msw@^2.14.0. @msw/cloudflare@0.0.1 declares a peer dependency of msw: >=2.14.1, one patch higher. Today ^2.14.0 resolves to msw@2.15.0, published 8 July 2026, so the mismatch is invisible. A lockfile or registry mirror that pins 2.14.0 exactly would sit outside the declared peer range.

Who this affects, and how to tell if that is you

The Vitest floor is worth calling out separately. Both packages declare peer dependencies of vitest ^4.1.0, @vitest/runner ^4.1.0 and @vitest/snapshot ^4.1.0, and Cloudflare's install command is npm i -D vitest@^4.1.0 @cloudflare/vitest-plugin. The docs state plainly that the package requires Vitest 4.1 or later. If you are on Vitest 3, the rename is your second migration, not your first, and Cloudflare maintains a separate Vitest 3 to Vitest 4 guide for the first one.

One more detail for anyone who cares about release hygiene: @cloudflare/vitest-plugin@1.0.0 depends on miniflare at 5.20260820.0-alpha and wrangler at 4.125.0. A 1.0.0 release pinning an alpha-tagged runtime dependency is worth knowing before you describe the upgrade as stable to your own stakeholders. The old 0.22.0 pinned miniflare 5.20260815.0-alpha and wrangler 4.124.0, so this is continuity rather than a regression.

What to do this week

Grep every repository for vitest-pool-workers in package.json, lockfiles and tsconfig.json files. npm will not tell you.

Run the codemod with --dry-run first, and with --files scoped if you are in a monorepo. Read the diff.

Separately, search your test files for outbound fetch calls that are currently mocked. Those are the tests that need real work, and they are the reason a rename becomes a half-day rather than ten minutes.

Confirm your Vitest major version before anything else. If it is 3, sequence that migration first.

The real cost here is the mocking layer, not the package name. That has been the shape of most dependency renames we have handled, and it is why a rename announcement is worth reading past the first paragraph. A similar gap between an SDK's headline change and what actually broke in test suites showed up in the Anthropic Python SDK 1.0 httpx2 mocking and tracing break. For teams already tracking Cloudflare's platform changes this month, the Cloudflare Browser Run concurrency and billing gap is the other item worth reading.

What is still unknown

Cloudflare has not published a support window or an end-of-life date for @cloudflare/vitest-pool-workers. The package is not deprecated on npm and 0.22.0 is nine days old at the time of writing, so it is unclear whether patch releases will continue on the old name.

It is also unclear whether @msw/cloudflare will reach a 1.0 release, and whether Cloudflare will vendor or co-maintain it. With zero GitHub releases and a last commit dated 7 July 2026, there is no public roadmap to read.

India-specific considerations

For Indian engineering teams running Workers in production, the practical impact is scheduling rather than cost. The Workers Paid plan is a minimum charge of $5 USD per month per account and none of these changes alter billing. What they alter is CI reliability during a migration window.

Where test fixtures contain personal data, the move from an in-process mock to a Mock Service Worker setup is a good moment to check what your fixtures actually hold. Under the Digital Personal Data Protection Act 2023, test data carrying real personal data is still personal data, and mocking layers are a common place for production payloads to be pasted in and forgotten.

FAQ

Did the Cloudflare Vitest API change in version 1.0.0?

No, the API did not change. The shipped TypeScript definition files for @cloudflare/vitest-pool-workers@0.22.0 and @cloudflare/vitest-plugin@1.0.0 differ on exactly one line, a documentation comment naming the config subpath. Every cloudflare:test export is identical, so a test suite calling only those exports needs nothing beyond the rename itself.

Why does the migration guide mention version 0.16.0?

Cloudflare's manual migration diff shows replacing "@cloudflare/vitest-pool-workers": "^0.16.0". That version was published on 5 May 2026, while the final release is 0.22.0 from 18 August 2026. A caret on a 0.x version only permits that minor, so current projects will not find the quoted string in their own package file.

Will npm warn me that the package was renamed?

No. As of 23 August 2026, @cloudflare/vitest-pool-workers@0.22.0 carries no deprecation field in its npm registry metadata. Nothing appears on install, npm outdated flags nothing, and CI passes. The only notice lives in Cloudflare's changelog post of 19 August 2026 and in the documentation.

Is the codemod safe to run across a monorepo?

@cloudflare/codemods is at 0.1.0, first published on 20 August 2026, with two versions in total. Cloudflare documents a --dry-run flag that previews changes and a --files <glob> flag that limits scope. Use both, review the resulting diff, and run it per package rather than repository-wide.

What happened to fetchMock in Workers tests?

It is gone, and it went before this rename. The string fetchMock appears zero times in the shipped type definitions of versions 0.16.0, 0.18.0, 0.20.0, 0.21.0, 0.22.0 and 1.0.0, and zero times in Cloudflare's workers/llms.txt documentation index. Outbound mocking now runs through the @msw/cloudflare integration instead.

How mature is the @msw/cloudflare package?

Version 0.0.1, published 30 June 2026, with two versions ever. The mswjs/cloudflare repository has 95 stars, zero GitHub releases, and a most recent commit dated 7 July 2026. It is MIT licensed in package.json, published by Mock Service Worker maintainer Artem Zakharchenko, and it is the only outbound mocking path Cloudflare documents.

Which Vitest version do I need?

You need Vitest 4.1 or later. Both @cloudflare/vitest-pool-workers@0.22.0 and @cloudflare/vitest-plugin@1.0.0 declare peer dependencies of vitest ^4.1.0, @vitest/runner ^4.1.0 and @vitest/snapshot ^4.1.0. Cloudflare's documented install command pins vitest@^4.1.0, and the docs state the requirement plainly, so teams still on Vitest 3 must complete that migration first.

Does the msw version in the docs match the peer dependency?

Not exactly, and the mismatch is one patch wide. Cloudflare's page documents msw@^2.14.0, while @msw/cloudflare@0.0.1 declares a peer dependency of msw: >=2.14.1. In practice ^2.14.0 resolves to msw@2.15.0, published 8 July 2026, so the gap stays hidden unless a lockfile pins 2.14.0 exactly.

How eCorpIT can help

We run test-suite migrations of exactly this shape: a rename that looks like a find-and-replace and turns out to be a mocking-layer rewrite. Our senior engineering teams audit Workers repositories for the old package name, scope and review codemod runs, and rebuild outbound mocks against the current documented path. If you want the lockfile grep and the migration plan done for you, our QA and test automation service covers it, and our software testing company page sets out how we staff this work. Book a test-suite migration review and we will tell you which of your repositories are affected.

References

1. @cloudflare/vitest-pool-workers is now @cloudflare/vitest-plugin, Cloudflare changelog, 19 August 2026
2. Migrate to Vitest plugin, Cloudflare Workers docs, last updated 20 August 2026
3. Mock outbound requests, Cloudflare Workers docs, last updated 20 August 2026
4. Test APIs, Cloudflare Workers docs, last updated 20 August 2026
5. Write your first test, Cloudflare Workers docs, last updated 20 August 2026
6. Vitest integration overview, Cloudflare Workers docs, last updated 20 August 2026
7. @cloudflare/vitest-plugin registry metadata, npm
8. @cloudflare/vitest-pool-workers registry metadata, npm
9. @cloudflare/codemods registry metadata, npm
10. @msw/cloudflare registry metadata, npm
11. msw registry metadata, npm
12. mswjs/cloudflare repository, GitHub
13. cloudflare-test.d.ts shipped in @cloudflare/vitest-plugin 1.0.0, jsDelivr
14. cloudflare-test.d.ts shipped in @cloudflare/vitest-pool-workers 0.22.0, jsDelivr
15. Workers pricing, Cloudflare, last updated 7 July 2026
16. Workers documentation index, llms.txt, Cloudflare

Last updated 23 August 2026.