@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@beta when Vite is selected and the plugin is missing or incompatible, and upgrades Wrangler when generated Wrangler tooling requires a newer version. The Vite plugin dependency remains set to the beta dist tag in package.json; package manager installation updates the project's lockfile. 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.