On this page · 14 sections
- What actually changed on 19 and 20 August 2026
- The rename really is API-clean, and that is checkable
- Gap one: the migration diff points at a version from May
- Gap two: npm gives no signal at all
- Gap three: the codemod is younger than the thing it migrates
- Gap four: outbound mocking is the real migration, and it predates the rename
- The dependency that deserves a second look
- Who this affects, and how to tell if that is you
- What to do this week
- What is still unknown
- India-specific considerations
- FAQ
- How eCorpIT can help
- References
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.
| Artifact | Version and date | What it implies |
|---|---|---|
@cloudflare/vitest-pool-workers final release |
0.22.0, 18 August 2026 | The version most current projects are pinned near |
| Version named in the migration diff | 0.16.0, 5 May 2026 | Six minor versions behind the final release |
@cloudflare/vitest-plugin first real release |
1.0.0, 20 August 2026 17:42 UTC | Published a day after the changelog announced it |
@cloudflare/codemods |
0.1.0, 20 August 2026 17:34 UTC | Pre-1.0, two versions, published before the target package |
@msw/cloudflare |
0.0.1, 30 June 2026 | The only documented outbound mocking path |
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
| Situation | Migration effort | First thing to check |
|---|---|---|
Tests use only cloudflare:test exports and SELF |
Codemod, minutes | Run the codemod with --dry-run |
Tests mock outbound fetch |
Rewrite of the mocking layer | Whether a setup file and setupFiles entry exist |
| Project still on Vitest 3 | Two migrations, sequenced | vitest version in package.json |
| Monorepo with several Workers packages | Codemod per package, reviewed | --files glob scoping |
| Repository untouched since May 2026 | No signal will reach you | Grep lockfiles for vitest-pool-workers |
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
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
Last updated 23 August 2026.
