workers-sdk/packages/codemods
ANT Bot 06acbd4bd2
Version Packages (#16915)
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
History 2026-11-16 11:47:53 +00:00
..
src Vite plugin v2 RC (#16921) 2026-11-16 11:05:13 +00:00
test Vite plugin v2 RC (#16921) 2026-11-16 11:05:13 +00:00
CHANGELOG.md Version Packages (#16915) 2026-11-16 11:47:53 +00:00
package.json Version Packages (#16915) 2026-11-16 11:47:53 +00:00
README.md Vite plugin v2 RC (#16921) 2026-11-16 11:05:13 +00:00
tsconfig.json [codemod] Add migration CLI (#14690) 2026-08-18 14:49:47 +01:00
tsup.config.ts [codemods] Share CLI and library dependency bundles (#16143) 2026-10-08 09:36:56 +00:00
turbo.json feat(codemods): add Wrangler-to-cf migration API (#15851) 2026-09-25 19:08:49 +01:00
vitest.config.mts [codemod] Add migration CLI (#14690) 2026-08-18 14:49:47 +01:00

@cloudflare/codemods

Codemods for upgrading Cloudflare developer projects.

Run a codemod by name:

npx @cloudflare/codemods vitest:v3-to-v4

Available codemods:

  • wrangler-to-cf - migrate a Wrangler configuration to the new cf configuration format
  • vitest:v3-to-v4 — migrate @cloudflare/vitest-pool-workers configuration from Vitest v3 to v4
  • vitest:pool-workers-to-vitest-plugin — rename @cloudflare/vitest-pool-workers to @cloudflare/vitest-plugin v1

Use --dry-run to list changes without writing them, --cwd <path> to target another project, or repeat --files <glob> to restrict the files considered. When the target is inside a Git worktree, the worktree must be clean. Use --force to bypass this safety check.

To migrate a Wrangler project with the default Vite bundler:

npx @cloudflare/codemods wrangler-to-cf --cwd ./path/to/project

The CLI detects a single root wrangler.json, wrangler.jsonc, or wrangler.toml. Pass --config <path> to select another file, or pass --bundler wrangler to retain Wrangler-specific tooling configuration. For this codemod, --files filters the selected Wrangler config and skips the migration when it does not match.

Programmatic usage

Codemods can also be run from JavaScript or TypeScript:

import { runCodemod } from "@cloudflare/codemods";

const { changedFiles } = await runCodemod("vitest:v3-to-v4", {
	cwd: process.cwd(),
	dryRun: false,
});

runCodemod accepts the same codemod names and aliases as the CLI. Its context also accepts optional files and force fields corresponding to the CLI flags, and setting dryRun lists changed files without writing them. It returns a CodemodResult containing changedFiles and rejects if the codemod cannot be run. The CLI's clean-worktree check also applies to programmatic runs.

Migrate Wrangler config to cf

Pass the exact Wrangler config file to migrateWranglerToCf:

import { migrateWranglerToCf } from "@cloudflare/codemods";

const result = await migrateWranglerToCf("./wrangler.jsonc", {
	bundler: "vite",
});

The options object and all of its fields are optional. The defaults are the Vite bundler, writes enabled, dirty-worktree protection enabled, and automatic dependency installation enabled. The migration installs cf when missing, installs @cloudflare/vite-plugin@^2.0.0-rc.0 when Vite is selected and the plugin is missing or older than the v2 release candidate, and upgrades Wrangler when generated Wrangler tooling requires a newer version. Dist tags such as beta count as incompatible, because they can stop pointing at a compatible release. Project-managed Vite plugin specifiers such as workspace: and catalog: are preserved; incompatible or unverified versions require a manual update. Set installDependencies to false to prevent dependency changes; required dependencies are then returned as blocking follow-ups. The migration always creates cloudflare.config.ts; selecting the Wrangler bundler also creates wrangler.config.ts when Wrangler-specific tooling config exists. Existing target files are never overwritten. Inspect result.followUps when result.status is needs-intervention.