The best way to control Claude Code, Codex and more from any computer or phone
| 1 | # Parity with `@cloudflare/vite-plugin` |
| 2 | |
| 3 | Alchemy's Vite plugin replaces `@cloudflare/vite-plugin` (checked against |
| 4 | **1.65.0**, the catalog version). Frameworks are built against the official |
| 5 | plugin's behavior, so anything they can observe must match. This file is the |
| 6 | inventory of that surface: every behavior is **matched** (with the test that |
| 7 | pins it), **different on purpose** (with the reason), or **out of scope**. |
| 8 | |
| 9 | Wrangler-specific behavior is out of scope: Alchemy configures Workers in |
| 10 | code, so `wrangler.json`, `.dev.vars`/`.env` loading, the Build Output |
| 11 | Specification, deploy config redirects, tunnels, keyboard shortcuts, agent |
| 12 | hints, update checks and the local explorer/observability UIs have no |
| 13 | counterpart. |
| 14 | |
| 15 | ## How parity is enforced |
| 16 | |
| 17 | | Test | What it checks | |
| 18 | | --- | --- | |
| 19 | | [`test/parity/config.test.ts`](./test/parity/config.test.ts) | Resolves one project with both plugins (`serve` and `build`, with and without `nodejs_compat`/`nodejs_als`, with user overrides, in production) and compares what frameworks read: each environment's `resolve`, `define`, `build`, `optimizeDeps`, the client environment, `appType`, `server.fs.deny`. | |
| 20 | | [`test/parity/build.test.ts`](./test/parity/build.test.ts) | Builds five project shapes with both plugins and compares the output: every file in `dist/`, entry chunk names and exports. | |
| 21 | | [`test/parity/constants.test.ts`](./test/parity/constants.test.ts) | Compares the runtime pieces ported verbatim (handler keys, additional module rules, `cloudflare:*` built-ins, Sandbox preview origins) with the installed release. | |
| 22 | | `packages/integration-tests/test/Cloudflare/Website/Vite*.test.ts` | The plugin's playgrounds and create-cloudflare's templates, deployed and under `alchemy dev`. | |
| 23 | |
| 24 | Upgrading `@cloudflare/vite-plugin` in the catalog re-runs all three |
| 25 | differential tests against the new release, so upstream drift in config, |
| 26 | build output or the ported runtime fails CI here instead of in an app. |
| 27 | Fixes ported from upstream `main` before a release ships them are listed in |
| 28 | [`test/parity/ahead-of-release.ts`](./test/parity/ahead-of-release.ts), which |
| 29 | the differential tests ignore until the installed release catches up. |
| 30 | |
| 31 | ## Inventory |
| 32 | |
| 33 | ### Plugin identity and options |
| 34 | |
| 35 | | Behavior | Status | Test | |
| 36 | | --- | --- | --- | |
| 37 | | Frameworks detect the plugin by a `vite-plugin-cloudflare` name prefix (React Router, vinext, Vike's `@universal-deploy`, Flue) | Matched (`vite-plugin-cloudflare:alchemy`) | `plugin-name.test.ts` | |
| 38 | | An official `cloudflare()` left in the config (or added by an async factory, e.g. RedwoodSDK) is neutralized | Matched | `plugin-name.test.ts`, `ViteTemplates.test.ts` | |
| 39 | | The `config` customizer of a neutralized `cloudflare()` still runs (Flue's `flueWorkerConfig()`) | Matched | `plugin-name.test.ts`, `examples/cloudflare-flue` | |
| 40 | | `rsc: { serverHandler: false }` for `@vitejs/plugin-rsc` | Matched | React Router RSC fixtures | |
| 41 | | Worker settings from `wrangler.json` / the customizer's result | Different: declared on the Website resource | — | |
| 42 | | `auxiliaryWorkers`, `persistState`, `remoteBindings`, `inspectorPort` | Different: separate `Cloudflare.Worker` resources, Alchemy state, `Alchemy.remote()` | — | |
| 43 | | `experimental.prerenderWorker` | Out of scope (experimental); prerendering through the preview server is matched | `ViteBuild.test.ts` | |
| 44 | |
| 45 | ### Resolved config |
| 46 | |
| 47 | | Behavior | Status | Test | |
| 48 | | --- | --- | --- | |
| 49 | | `appType: "custom"`; `server.fs.deny` (Vite's, credentials, key stores, `.wrangler`) | Matched, plus Alchemy's state and stack files | `config.test.ts`, `ViteRuntime.test.ts` (sensitive files) | |
| 50 | | Worker environment `resolve` (conditions, `noExternal`, built-ins) | Matched | `config.test.ts` | |
| 51 | | `cloudflare:durable-objects` is a runtime built-in | Matched ahead of the release (upstream `main`, after 1.65.0) | `constants.test.ts`, `config.test.ts` via `test/parity/ahead-of-release.ts` | |
| 52 | | `define`: `process.env.NODE_ENV`; `process.env` as `{}` without `nodejs_compat` | Matched | `config.test.ts`, `ViteRuntime.test.ts` (NODE_ENV) | |
| 53 | | `build`: target (`es2026` on Rolldown), `cssTarget`, manifest, source maps, `emitAssets`, `copyPublicDir`, `ssr`, output dir, `index` entry input | Matched | `config.test.ts`, `build.test.ts` | |
| 54 | | `optimizeDeps`: entries, `development` condition, Node.js and `cloudflare:*` excluded | Matched | `config.test.ts` | |
| 55 | | esbuild `supported.using` scoped to Worker environments (Vite 6/7) | Matched | `config.test.ts` (Rolldown); code path mirrors upstream | |
| 56 | | Assets-only projects declare no Worker environments | Matched | `config.test.ts`, `build.test.ts` | |
| 57 | |
| 58 | ### Build |
| 59 | |
| 60 | | Behavior | Status | Test | |
| 61 | | --- | --- | --- | |
| 62 | | Default `buildApp`: Worker environments, then the client; a client with no entry builds for `public/` or Worker-imported assets; imported assets move to the client output | Matched | `build.test.ts` | |
| 63 | | A user's own `buildApp` is kept | Matched | `ViteRuntime.test.ts` (custom buildApp) | |
| 64 | | Additional modules (`.wasm`, `.bin`, `.txt`, `.html`, `.sql`, subpath imports), `.wasm?init` | Matched | `build.test.ts`, `ViteRuntime.test.ts` (additional modules) | |
| 65 | | Node.js compat: unenv aliases, injected globals and polyfills | Matched | `ViteNodeCompat.test.ts` | |
| 66 | | Unexpected Node.js imports warn without `nodejs_compat` (build and dev) | Matched | `dev-plugin.test.ts`, `ViteNodeCompat.test.ts` (als) | |
| 67 | | `using` kept native | Matched | `build.test.ts`, `ViteBuild.test.ts` | |
| 68 | | Deployed modules are the output as written to disk; `.vite/` metadata isn't deployed | Matched | `ViteTemplates.test.ts` (Vike) | |
| 69 | |
| 70 | ### Dev server |
| 71 | |
| 72 | | Behavior | Status | Test | |
| 73 | | --- | --- | --- | |
| 74 | | Module runner in workerd: HMR, source-mapped stacks, sealed exports, `cloudflare:workers` `env` without internal bindings | Matched | `ViteRuntime.test.ts` (importable env, error page) | |
| 75 | | `__VITE_ENVIRONMENT_RUNNER_IMPORT__` for child environments (`import.meta.viteRsc.loadModule`) | Matched | `ViteRuntime.test.ts` (child environment), React Router RSC | |
| 76 | | Export wrappers for `WorkerEntrypoint`, `DurableObject`, `WorkflowEntrypoint` and their handler keys | Matched | `constants.test.ts`, `ViteRuntime.test.ts` (entrypoints, Durable Objects, Workflows) | |
| 77 | | Restart when the entry's export types change | Matched | `dev-export-types.test.ts` | |
| 78 | | Restart when an additional module file changes | Matched | `dev-assets.test.ts` | |
| 79 | | Uncaught `fetch` errors on Vite's error page | Matched | `ViteRuntime.test.ts` (error page) | |
| 80 | | An unresolvable `main` fails the dev start | Matched | `ViteRuntime.test.ts` (config changes) | |
| 81 | | `run_worker_first` routing ahead of Vite's middlewares; the router and asset worker | Matched | `ViteAssetRouting.test.ts` | |
| 82 | | HTML through `transformIndexHtml`, `public/` HTML raw, `server.headers` on assets | Matched | `dev-assets.test.ts` | |
| 83 | | Vite's bundled dev mode (`experimental.bundledDev`) | Matched | `ViteRuntime.test.ts` (bundled dev) | |
| 84 | | The Worker's `ASSETS` binding runs through Vite's middlewares | Matched | `dev-assets.test.ts` | |
| 85 | | WebSockets to the Worker; Vite's HMR socket left alone unless from a Sandbox preview origin; a socket another `upgrade` listener answers is left to it | Matched | `websockets.test.ts`, `constants.test.ts`, `ViteRuntime.test.ts` (WebSockets) | |
| 86 | | A refused WebSocket upgrade | Different: the Worker's response reaches the client (upstream resets the socket) | `websockets.test.ts` | |
| 87 | | `/cdn-cgi/local/*` trigger endpoints and the legacy `/cdn-cgi/mf/*`, `/cdn-cgi/handler` paths | Matched | `ViteRuntime.test.ts` (scheduled and email) | |
| 88 | | Public URL from the dev server's host, port and HTTPS | Matched | `ViteStreaming.test.ts` (HTTPS) | |
| 89 | | `X-Forwarded-Host`, `X-Forwarded-Proto` (case-insensitive), `ctx.access` from `dev.access` | Matched | `forwarded-host.test.ts`, `ViteRuntime.test.ts` (headers, Access) | |
| 90 | | The Worker's response status text (dev and preview) | Matched (upstream `main`, after 1.65.0) | `dev-proxy.test.ts` | |
| 91 | | Repeated `Set-Cookie` request headers reach the Worker as separate values | Matched (upstream `main`, after 1.65.0) | `dev-proxy.test.ts` | |
| 92 | | Outbound `fetch`: `CF-Worker`, no `CF-Connecting-IP`, `cf.image` | Matched | `ViteRuntime.test.ts` (CF-Worker, cf.image) | |
| 93 | | Restart after a workerd crash | Matched | `ViteRuntime.test.ts` (workerd crashes) | |
| 94 | | Containers built from a Dockerfile | Matched | `ViteRuntime.test.ts` (containers) | |
| 95 | | Alchemy's runtime variables (`ALCHEMY_*`) in `env` and `process.env` | Different: Alchemy's runtime reads them; documented on `env` | `ViteNodeCompat.test.ts` (process-populated-env) | |
| 96 | | `/__debug` inspector page, structured log levels | Out of scope (presentation) | — | |
| 97 | |
| 98 | ### Preview |
| 99 | |
| 100 | | Behavior | Status | Test | |
| 101 | | --- | --- | --- | |
| 102 | | `vite preview` serves the built Worker and its assets | Matched | `preview-plugin.test.ts`, `ViteBuild.test.ts` (prerendering) | |