skip to content

Local Runs & Simulation

wrangler dev runs a Worker locally in workerd through Miniflare, with simulated or remote bindings. Interviewers ask what local mode cannot reproduce and where local data lives.

on this pageshow

explore

questions

6

In Wrangler 4, what does wrangler dev run on your machine by default, and how does wrangler dev --remote differ?

level: juniorimportance: must knowfreq 68%

answer

  1. same runtime as production
  2. a simulator wrapping workerd
  3. bindings start empty, on disk
  4. one binding never runs locally
  5. --remote uploads a temporary preview

basics

~20 s

By default wrangler dev runs the Worker locally in workerd, the production runtime, through the Miniflare simulator, with most bindings simulated on disk. wrangler dev --remote uploads the code to a temporary preview on Cloudflare's network, where every binding is real.

solid answer

~40 s

Plain `wrangler dev` starts a local server (port 8787 by default) and runs the Worker inside `workerd`, the open-source runtime Cloudflare runs in production, driven by the Miniflare simulator. KV, D1, R2, Durable Objects, Queues and Workflows get local simulations that start empty, with stored data kept under `.wrangler/state`; Workers AI is the exception, because it has no local simulator and always calls Cloudflare. Nothing is deployed. `wrangler dev --remote` (alias `-r`) uploads the code to a temporary preview on Cloudflare's network and re-uploads on every save, so every binding is the deployed resource; it is slower, needs an authenticated Wrangler and has no Vite plugin equivalent. Cloudflare's docs now file `--remote` as the legacy mode and recommend local execution plus `remote: true` on the few bindings that must be real.

code

bash · 11 lines
bash
# Local: workerd through Miniflare, bindings simulated under .wrangler/state
npx wrangler dev

# Same, on a chosen address and port
npx wrangler dev --ip 127.0.0.1 --port 8721

# Local, with every remote: true binding switched back to its local simulation
npx wrangler dev --local

# Fully remote: code uploaded to a temporary preview, all bindings real
npx wrangler dev --remote

go deeper

for a junior

Recall the default: wrangler dev runs the Worker on your machine in workerd through Miniflare, with empty local copies of each binding, while --remote uploads it to a temporary preview on Cloudflare.

for a middle

Explain the two axes, where code runs and where each binding points, and how remote: true moves one binding, --local switches them all back, and --remote moves everything.

for a senior

Show you know what each mode costs: --remote writes real data and iterates slowly, local mode hides network-only behaviour, and Workers AI is billed even locally.

for a principal

Frame the team default: local execution as the norm, remote bindings only against non-production resources, and --remote reserved for behaviour that exists only on Cloudflare's network.

## Two separate questions: where the code runs, where the bindings point Cloudflare's local-development model splits one fuzzy idea into two independent choices: - **Worker execution**: where your JavaScript or TypeScript actually runs, on your laptop or on Cloudflare's infrastructure. - **Bindings**: what `env.MY_KV`, `env.DB` or `env.BUCKET` talk to, a local simulation or the real deployed resource. Most confusion about `wrangler dev` comes from treating these as one switch. In Wrangler 4 they are two: the command decides where code runs, and each binding can separately be pointed at a real resource. ## Default mode: local workerd through Miniflare Running `wrangler dev` with no flags: 1. Bundles the Worker named by `main` in the Wrangler configuration file. 2. Starts **`workerd`**, the open-source runtime that executes Workers in production, managed by **Miniflare**, Cloudflare's simulator library. Because the runtime is the real one, Web APIs, the module-format `export default { fetch }` handler and compatibility flags behave as they will when deployed. 3. Serves the Worker on `http://localhost:8787` (change it with `--port` and `--ip`), reloading on every file save. 4. Gives every binding a **local simulation**: KV, D1, R2, Durable Objects, Queues and Workflows are all backed by files under `.wrangler/state` in the project. They start empty; you seed them with `wrangler kv key put --local`, `wrangler d1 execute --local` and similar commands, or through the Worker's own requests. The local server also runs with `TZ=UTC`, so `Date` and `Intl` see the same timezone as production, and pressing `d` in the terminal opens Chrome DevTools against the local isolate for breakpoints and CPU profiles. One binding breaks the pattern: **Workers AI has no local simulator and never will**. Under plain `wrangler dev` an `ai` binding still calls Cloudflare, so it needs an authenticated Wrangler and is billed. If the binding omits `remote`, Wrangler warns that it "always access[es] remote resources, and so may incur usage charges even in local dev"; setting `"remote": false` on it is an error. ## Fully remote mode: wrangler dev --remote `wrangler dev --remote` (alias `-r`) changes **where the code runs**. Wrangler uploads the Worker to a temporary preview on Cloudflare's network and re-uploads it on each save; your requests still go to localhost and are proxied there. Consequences: - **Every binding is the deployed resource.** You cannot keep one binding simulated, and writes hit real data. - **Iteration is slower**, because each change is an upload. - It needs a logged-in Wrangler (or an API token) and an account. - A remote session enforces a limit of 50 routes per zone. - The Cloudflare Vite plugin has **no equivalent**; it only develops locally. Cloudflare's local-development docs now file this mode as legacy and keep it for behaviour "highly specific to Cloudflare's network" that cannot be simulated or reached through remote bindings. ## The middle path: local code, selected remote bindings Since remote bindings became generally available (Wrangler 4.36, September 2025), the recommended setup is local execution with `"remote": true` added only to the bindings that must be real, for example a Vectorize index or a staging R2 bucket. The Worker keeps local speed and DevTools while those calls go to Cloudflare. `wrangler dev --local` (alias `-l`) temporarily disables every remote binding. | | `wrangler dev` | `wrangler dev` + `remote: true` | `wrangler dev --remote` | |---|---|---|---| | Worker code runs | Your machine (workerd) | Your machine (workerd) | Cloudflare preview | | KV, D1, R2 data | Local simulation | Chosen bindings real | All real | | Durable Objects | Local | Local | Real | | Works offline | Yes, apart from AI | No for the remote ones | No | | Vite plugin support | Yes | Yes | No | ## What an interviewer is listening for - That local mode uses the **production runtime**, not a Node.js imitation: Miniflare 2 emulated the runtime in Node.js, and since Miniflare 3 it drives workerd. - That local bindings are **simulations with their own empty data**, so nothing a laptop writes reaches production unless a binding is marked remote. - That `--remote` trades speed for fidelity and touches real data, so it is a tool for network-specific behaviour, not a daily default. - That Workers AI is the one binding that is real even in plain local mode, which matters for cost and for working offline.

  • If local mode uses the production runtime, why can a Worker still behave differently once deployed?
    The runtime is the same but the platform around it is not. Local KV is one on-disk store with no propagation delay, `request.cf` comes from a cached snapshot, configured `limits` such as `cpu_ms` are not enforced, Cron Triggers do not fire on their own, and there is one local instance instead of a global network. Those differences, not the JavaScript engine, are what local testing misses.
  • When is wrangler dev --remote still the right tool?
    When the behaviour under test exists only on Cloudflare's network and no remote binding can reach it, for example how a route on a real zone is matched or how a request looks after passing through the edge. For data fidelity alone, local mode with `remote: true` on the specific bindings is faster and keeps the rest of the Worker local.
  • Does plain wrangler dev work with no internet connection?
    Mostly. Code execution and the simulated KV, D1, R2, Durable Object, Queues and Workflow bindings are local. A Workers AI binding, or any binding marked `remote: true`, needs the network and Wrangler authentication, and Miniflare's first fetch of the `request.cf` snapshot falls back to built-in sample values when it cannot reach Cloudflare.

Local wrangler dev is a flight simulator built around a real cockpit: the controls, the runtime, are genuine, but the weather, traffic and airports around them are simulated. wrangler dev --remote is a short supervised flight in the real aircraft, slower to arrange and with real consequences.

  • Says local mode runs the Worker in a Node.js process that imitates the Workers APIs.
  • Believes plain wrangler dev reads and writes the production KV namespace.
  • Thinks wrangler dev --remote deploys to production and sends it live traffic.
  • Assumes every binding, Workers AI included, works offline in local mode.
  • Treats --remote as needed whenever a single binding must be real.

Assumes Wrangler 4.149; remote bindings (remote: true) are generally available since Wrangler 4.36 (September 2025), and the docs now describe wrangler dev --remote as the legacy fully remote mode.

open as a page

During wrangler dev, how does Wrangler load local secrets from .dev.vars and .env files, and which value wins when they overlap?

level: middleimportance: should knowfreq 48%

basics

~20 s

Wrangler reads .dev.vars beside the Wrangler file, or, only when no .dev.vars file applies, the .env files. Their values override the config's vars locally. A .dev.vars.<env> file replaces .dev.vars, while .env files for an environment merge.

open as a page

Where does Wrangler keep a Worker's local KV, D1, R2 and Durable Object data during wrangler dev, and how does --persist-to change it?

level: middleimportance: should knowfreq 42%

basics

~20 s

Local binding data lives in .wrangler/state next to the Wrangler configuration file and survives restarts. --persist-to moves it to another directory, and every Wrangler command that seeds or reads that data must be given the same --persist-to.

open as a page

With Cloudflare remote bindings, how does a Worker using KV, D1 and a Durable Object under wrangler dev also reach the real Workers AI binding?

level: middleimportance: should knowfreq 38%

basics

~20 s

Keep the Worker local and mark the AI binding remote: true; Workers AI has no local simulator, so its calls go to Cloudflare while KV, D1 and the Durable Object stay simulated. Other bindings opt in the same way; Durable Objects cannot.

open as a page

A Cloudflare Worker passed every check under wrangler dev but misbehaves in production; which platform behaviours does local mode not reproduce?

level: seniorimportance: should knowfreq 40%

basics

~20 s

Local mode runs the real runtime but not the network around it: KV has no cross-location propagation delay, request.cf is one cached snapshot, configured limits such as cpu_ms are not enforced, and Cron Triggers never fire on their own.

open as a page

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%

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.

open as a page