Migrate from Wrangler to cf

Quick example

# Node.js 22.18 or newer
npm i -g cf

# Run inside your existing project
cf migrate --dry-run

# Apply the migration after reviewing the plan
cf migrate

cf migrate is Cloudflare’s migration tool. This guide helps you review its output; it does not implement a replacement converter.

Start with a clean working tree

Commit or otherwise preserve your existing changes first. The command includes a Git worktree check. --force bypasses that protection, so use it only when you have intentionally accounted for your local changes.

Before migrating, install the project’s dependencies and check its local Wrangler version. Projects that continue building through Wrangler need version 4.136.0 or later for cf dev, cf build and cf deploy. Do not run those project commands against an unmigrated Wrangler project: automatic configuration does not read its Wrangler file.

# Inspect existing changes
git status --short

# Select a file explicitly when necessary
cf migrate wrangler.jsonc --dry-run

The migration accepts Wrangler configuration files, including TOML, JSON and JSONC. Run it from the project that owns the configuration so dependency and script edits target the intended package.

Choose the build integration

The CLI selects Vite when @cloudflare/vite-plugin is declared; otherwise it defaults to the Wrangler bundler. You can explicitly select the path your project needs.

cf migrate --bundler vite --dry-run
cf migrate --bundler wrangler --dry-run

Vite being present for tests does not automatically mean Vite owns your production build. Review package scripts and plugin integration together. The choice of bundler and the CLI’s later framework detection are separate things to verify.

Read the dry-run follow-up list before applying changes. An exit status of 1 with [required] items means the migration needs manual work; it does not by itself mean the conversion failed.

Review the result

After migration, review the full diff rather than only checking that cloudflare.config.ts exists:

1. Compare the Worker name, compatibility date, entrypoint, bindings and resource identifiers with the original deployment.
2. Check the selected bundler and build settings. Vite settings may need to be moved by hand; Wrangler builds use the generated wrangler.config.ts.
3. Resolve each [required] item and TODO(@cloudflare) in cloudflare.config.ts, then remove its migration-incomplete throw statement.
4. Review each Wrangler environment as a cf mode. The default mode differs between Vite and Wrangler builds; pass --mode explicitly when the target matters.
5. Update package scripts and type generation yourself. cf migrate leaves scripts, vite.config.ts, .gitignore, tsconfig.json and source files unchanged.

By default the command installs cf as a project dependency. --no-install skips dependency installation, but you must install it before running the project. Add .cloudflare/ to .gitignore; include generated .cloudflare/types in TypeScript after cf workers types or your Vite build writes them.

Validate before switching CI

cf dev
cf build
cf deploy --dry-run

Test the same application behavior you tested with Wrangler: requests, local data access and any stateful classes. cf deploy --dry-run builds and validates without API requests, though a project missing cloudflare.config.ts can still be configured locally first. Review the deploy workflow before trying a deployment.

A successful migration is a source transformation, not evidence that production resources, secrets or databases have moved. Use the binding examples to inspect resource references. Preserve an easy rollback to the original scripts until the new workflow is validated.

Common mistakes

• Running migration with unrelated uncommitted edits and losing track of which changes belong to the migration.
• Treating a generated config as proof that a framework supports all cf build flags.
• Assuming a renamed binding also renames the deployed resource.
• Updating the CI command before testing the new build output locally.

See cf vs Wrangler for the transition context and command reference for workflows that have changed shape.