skip to content

How do the Cloudflare Vite plugin and wrangler's getPlatformProxy() differ in giving a framework's local dev server access to Workers bindings?

level: middleimportance: nice to knowfreq 25%

answer

  1. inside workerd versus beside it
  2. Vite's Environment API
  3. proxies into a Node.js process
  4. the renamed bindings helper
  5. environment chosen at build time

basics

~20 s

The Cloudflare Vite plugin runs the Worker's code itself inside workerd during vite dev, with real bindings APIs. getPlatformProxy() leaves the code in Node.js and hands it env, cf, ctx and caches proxied to a local workerd, without running the Worker.

solid answer

~40 s

The Cloudflare Vite plugin (`@cloudflare/vite-plugin`, added as `cloudflare()` in the Vite config) uses Vite's Environment API to execute the Worker's server code in `workerd` during `vite dev`, with hot module replacement, the same Miniflare simulations and remote bindings as `wrangler dev`; `vite build` writes an output Wrangler config that `wrangler deploy` and `vite preview` use. `getPlatformProxy()`, imported from `wrangler`, is for a dev server that stays in Node.js: it reads the Wrangler file, starts a local `workerd` and returns `env` proxies, a mock `cf`, a `ctx` whose `waitUntil()` does nothing, a no-op `caches` and `dispose()`. It never runs your Worker, so runtime-only behaviour is not exercised and a Durable Object binding needs a `script_name` pointing at another Worker. It replaced `getBindingsProxy()`, removed in Wrangler 4.

code

javascript · 9 lines
javascript
import { getPlatformProxy } from "wrangler";

const { env, cf, dispose } = await getPlatformProxy();

console.log("seeded:", await env.CACHE.get("seeded"));
const row = await env.DB.prepare("SELECT COUNT(*) AS n FROM hits").first();
console.log("hits:", row.n, "country:", cf.country);

await dispose();

go deeper

for a junior

Recall that the Vite plugin runs Worker code in workerd during vite dev, while getPlatformProxy() gives a Node.js process proxied bindings.

for a middle

Explain what getPlatformProxy() returns, why it cannot exercise runtime behaviour, and how CLOUDFLARE_ENV and the build's output config work with the Vite plugin.

for a senior

Anticipate the traps: internal Durable Objects needing script_name, no-op ctx and caches, the v3 persistence path, and getBindingsProxy removed in Wrangler 4.

for a principal

Prefer runtime fidelity: standardise on the Vite plugin where the framework supports it and reserve getPlatformProxy() for servers that cannot run in workerd.

## The problem both tools solve Many web frameworks ship their own development server, which runs in **Node.js**. A Worker's server code, though, expects `env.MY_KV`, `env.DB` and the rest of the Workers bindings, which exist only inside the Workers runtime. Cloudflare offers two ways to bridge that gap, and they differ in **where your code runs**. ## The Cloudflare Vite plugin: your code runs in workerd The plugin is the package `@cloudflare/vite-plugin`, added to the Vite configuration as `cloudflare()`: ```js import { defineConfig } from "vite"; import { cloudflare } from "@cloudflare/vite-plugin"; export default defineConfig({ plugins: [cloudflare({ persistState: { path: "./dev-data" } })], }); ``` - It uses Vite's **Environment API** to run the Worker's server code inside **`workerd`** during `vite dev`, so the runtime matches production and bindings are the real Workers APIs. - It keeps Vite's **hot module replacement** and plugin pipeline. - Bindings use the same **Miniflare simulations** and the same `.wrangler/state` folder as `wrangler dev`; `persistState` moves or disables that, and `remoteBindings` (default `true`) controls bindings marked `remote: true`. - Local secrets come from `.dev.vars` or `.env`, and a Wrangler environment is chosen with **`CLOUDFLARE_ENV`**, for example `CLOUDFLARE_ENV=staging vite dev`. - `vite build` writes an **output Wrangler configuration** into the build directory, a snapshot flattened for the chosen environment. `wrangler deploy` and `vite preview` find it automatically, so `wrangler deploy --env staging` does not apply: the environment is fixed at build time with `CLOUDFLARE_ENV=staging vite build`. - `vite preview` runs the built output in the Workers runtime, a last local check before deploying. - The DevTools inspector listens on port `9229` by default (`inspectorPort` changes or disables it). - There is no fully remote mode: the plugin has no equivalent of `wrangler dev --remote`. ## getPlatformProxy(): bindings delivered into Node.js `getPlatformProxy()` comes from the `wrangler` package and is meant **only for Node.js**; it cannot run inside the Workers runtime. ```js import { getPlatformProxy } from "wrangler"; const { env, cf, ctx, caches, dispose } = await getPlatformProxy(); const greeting = await env.CACHE.get("greeting"); ``` It reads the Wrangler configuration file, starts a local `workerd` holding the bindings, and returns: - **`env`**: proxies to the local bindings (vars, secrets from `.dev.vars`, KV, R2, D1, Queues, service bindings, Hyperdrive and Workers AI, among others). - **`cf`**: a mock of `request.cf`. - **`ctx`**: `waitUntil()` and `passThroughOnException()` that do nothing. - **`caches`**: an emulation of the Cache API whose operations currently do nothing. - **`dispose()`**: stops the `workerd` process. Options include `configPath`, `environment`, `persist` and `remoteBindings` (default `true`). In TypeScript, `getPlatformProxy<Env>()` types the returned `env` with the project's binding interface. By default `persist` uses the location Wrangler uses, so data seeded with `wrangler kv key put --local` or written during `wrangler dev` is visible through the proxy. ## Where getPlatformProxy() falls short 1. **It does not run your Worker.** Only the bindings live in `workerd`; your code runs in Node.js with Node's globals, so a runtime-specific bug cannot show up. 2. **Durable Objects need a separate Worker.** A binding to a class defined in the same Worker does not work locally; give the binding a `script_name` naming another Worker that exports the class and run that Worker too. 3. **The proxies are a best-effort emulation**, and the docs say small differences from production bindings are possible. 4. **Hyperdrive values are passthrough**: `connectionString` points at the database you configured, not at a pooled connection. ## Choosing between them | | Cloudflare Vite plugin | `getPlatformProxy()` | |---|---|---| | Where Worker code runs | `workerd` | Node.js | | Runtime fidelity | Production runtime | Node.js, bindings only | | Needs Vite | Yes | No | | Durable Objects in the same Worker | Yes | No, needs `script_name` | | Typical use | Vite-based apps and standalone Workers | A framework dev server that cannot run in `workerd` | ## History worth knowing `getPlatformProxy()` was first called `getBindingsProxy()`; it was renamed when it grew `cf`, `ctx` and `caches`, and **Wrangler 4 removed the old name**. Code still importing `getBindingsProxy` fails and should switch to `getPlatformProxy()`. Where a framework can run its server code through the Vite plugin, that path exercises the real runtime, which proxying bindings into Node.js cannot.

  • Why does a Durable Object binding fail through getPlatformProxy() when the class lives in the same Worker?
    `getPlatformProxy()` does not run your Worker's code, so a class defined there is never instantiated; Wrangler warns that such internal Durable Objects will not work in local development. Define the class in a separate Worker, add `script_name` naming it to the binding, and run that Worker in its own `wrangler dev` session or alongside your app in one multi-config session.
  • With the Vite plugin, how do you deploy a staging build?
    Choose the environment at build time: `CLOUDFLARE_ENV=staging vite build` writes an output Wrangler configuration flattened for staging, and `wrangler deploy` then picks that file up. Passing `--env staging` to `wrangler deploy` does not apply, because the environment was already resolved during the build.

  • Believes getPlatformProxy() runs the Worker's fetch handler inside workerd.
  • Still imports getBindingsProxy() from wrangler in a Wrangler 4 project.
  • Expects ctx.waitUntil() from getPlatformProxy() to keep work running.
  • Selects the Vite plugin's environment with wrangler deploy --env after vite build.
  • Thinks the Vite plugin keeps its own data separate from wrangler dev by default.

Assumes Wrangler 4.149: getBindingsProxy() was removed in Wrangler 4.0 in favour of getPlatformProxy(), and the Cloudflare Vite plugin selects Wrangler environments with CLOUDFLARE_ENV at dev and build time.