Cloudflare Vite plugin: local dev that matches production

TL;DR: That is the whole point: your dev loop executes against workerd, not Node, so runtime differences surface in dev instead of production. ## When to use it over wrangler dev - Full-stack projects (Hono + React SPA, vinext/Next.js) where Vite already owns the build. # The Cloudflare Vite plugin @cloudflare/vite-plugin

Fix

1. That is the whole point: your dev loop executes against workerd, not Node, so runtime differences surface in dev instead of production. ## When to use it over wrangler dev - Full-stack projects (Hono + React SPA, vinext/Next.js) where Vite already owns the build. Expected: this specific failure stops.

2. npm run dev. Expected: this specific failure stops.

Details

The Cloudflare Vite plugin @cloudflare/vite-plugin runs your Worker inside the Cloudflare Workers runtime during local development, with local emulations of your bindings. The Hono and Next.js guides both scaffold on the Vite plugin. - Any project where you want HMR plus Workers runtime fidelity in one dev server ( / vite dev ). wrangler dev remains fine for single-file Workers and quick iteration without a Vite setup. ## Environments with the plugin With the Vite plugin you select the Cloudflare environment via the CLOUDFLARE_ENV environment variable, not --env . CLOUDFLARE_ENV=production vite build produces a flattened wrangler.json vite.config.ts plugin config and wrangler.jsonc bindings in sync; the plugin reads the Wrangler file for binding emulation. - Test binding-dependent code paths in the plugin dev server, not plain node, before concluding a binding is broken. - In CI, make sure the build command sets CLOUDFLARE_ENV

When to use

You hit exactly this: Cloudflare Vite plugin: local dev that matches production in Cloudflare Vite plugin.

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

Cloudflare Vite plugin.

Root cause

to the intended environment; the default top-level config is the dev environment in most setups.

Edge cases

• for the production environment: top-level plus inheritable keys merged, non-inheritable keys resolved to the environment's values. ## Checklist - Keep.

Verified against the live Vite plugin docs and Cloudflare Environments reference: plugin runs the Workers runtime locally with binding emulation, CLOUDFLARE_ENV selection, flattened wrangler.json output. Refs: https://developers.cloudflare.com/workers/vite-plugin/ and https://developers.cloudflare.com/workers/vite-plugin/reference/cloudflare-environments/