skip to content

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%

answer

  1. a hidden folder beside the config
  2. survives restarts, not commits
  3. every command must agree on the path
  4. Wrangler 4 flipped a CLI default

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.

solid answer

~50 s

Miniflare stores each simulated binding under `.wrangler/state` (currently a `v3` subfolder with `kv`, `d1`, `r2` and `do` directories), resolved next to the Wrangler configuration file, so data written in one `wrangler dev` session is still there in the next. Deleting the folder resets everything; deleting a subfolder resets one binding type. `wrangler dev --persist-to <dir>` puts the state somewhere else, but the flag must be repeated on every run and on every data command, such as `wrangler kv key put --local --persist-to <dir>` or `wrangler d1 execute --local --persist-to <dir>`, or they quietly write to a different store. In Wrangler 4 the `wrangler kv key` and `wrangler r2 object` commands default to local data, so `--remote` is what reaches Cloudflare. Durable Objects have no Wrangler seeding command: you seed them through the Worker or Local Explorer.

code

bash · 10 lines
bash
# One state directory for the dev server and every seeding command
npx wrangler dev --persist-to ./dev-data

# In another terminal, seed the same directory
npx wrangler kv key put greeting hi --binding CACHE --local --persist-to ./dev-data
npx wrangler d1 execute lab-db --file ./seed.sql --local --persist-to ./dev-data
npx wrangler r2 object put assets/logo.png --file ./logo.png --local --persist-to ./dev-data

# Reset all local data kept in the default location
rm -rf .wrangler/state

go deeper

for a junior

Recall that local binding data sits in .wrangler/state beside the Wrangler file, persists across restarts, and resets when you delete the folder.

for a middle

Explain how --persist-to moves the state, why every seeding command needs the same path plus --local, and which bindings have seeding commands.

for a senior

Diagnose 'seeded but not visible' as a path mismatch, and catch Wrangler 3 scripts whose kv or r2 commands now hit local data instead of Cloudflare.

for a principal

Decide how a team shares fixtures: committed seed scripts that rebuild .wrangler/state on demand rather than committed state, with explicit --local or --remote in every script.

## Local bindings are files on your disk Under `wrangler dev`, every simulated binding (Workers KV, D1, R2, Durable Objects, the Cache API, and the rest) is backed by Miniflare's storage on the local filesystem rather than by memory, so a counter in a Durable Object or a row in a D1 table survives stopping and restarting the dev server. By default the data lives in: - **`.wrangler/state`**, resolved relative to the **Wrangler configuration file** (or the working directory when there is none). - Inside it, Wrangler 4 currently writes a **`v3`** folder with one subfolder per binding type: `kv`, `d1`, `r2`, `do`, plus `cache` and others. - Durable Object data is grouped per class, in a folder named after the Worker and the class, for example `do/local-dev-lab-Counter`. - Each project gets its own state folder, because the default path follows the Wrangler file; two Workers share local data only when both are pointed at the same directory. Wrangler and the Cloudflare Vite plugin use the same default location, so both tools see the same local data out of the box. The local stores **start empty**: local resources are created automatically from the binding definitions, but no data is copied from the deployed resources. ## Resetting and ignoring local state - **Reset everything**: delete `.wrangler/state`; Miniflare recreates it on the next `dev` run. - **Reset one binding type**: delete just that subfolder, such as `.wrangler/state/v3/d1`. - **Keep it out of version control**: add `.wrangler` (or your custom persistence folder) to `.gitignore`; it is developer-local data, and it can hold whatever test data or personal records you loaded. ## Moving it with --persist-to `wrangler dev --persist-to ./dev-data` stores the state under `./dev-data` instead. Three rules trip teams up: 1. The path is **not remembered**. It must be passed on every `wrangler dev` run, usually through a package script. 2. Every **data command** must use the same path together with `--local`. `wrangler kv key put greeting hi --binding CACHE --local --persist-to ./dev-data` writes where the dev server reads; drop `--persist-to` and the key lands in `.wrangler/state`, invisible to that session. 3. `wrangler d1 execute` refuses `--persist-to` without `--local` ("Cannot use --persist-to without --local"). A custom path is useful for keeping several fixture sets side by side, sharing one state folder between two Workers' projects, or pointing a CI job at a throwaway directory. ## Seeding local data | Binding | How to seed it locally | |---|---| | Workers KV | `wrangler kv key put <KEY> <VALUE> --binding <NAME> --local`, or `wrangler kv bulk put <file.json> --binding <NAME> --local` | | R2 | `wrangler r2 object put <bucket>/<key> --file <path> --local` | | D1 | `wrangler d1 execute <database> --file ./seed.sql --local`, or `--command "<SQL>"` | | Durable Objects | No Wrangler command: call the Worker (a development-only route) so the object writes its own state, or insert rows through Local Explorer for classes declared with `new_sqlite_classes` | In **Wrangler 4**, `wrangler kv key` and `wrangler r2 object` commands **default to local storage**, the reverse of Wrangler 3, where they defaulted to the deployed resource. A script written for Wrangler 3 that relied on the default to update production now edits the local copy instead; pass `--remote` explicitly when you mean Cloudflare. ## Other tools reading the same state - **Cloudflare Vite plugin**: the `persistState` option sets the folder (`{ path: "./dev-data" }`) or disables persistence with `false`. - **`getPlatformProxy()`** from `wrangler`: its `persist` option defaults to the location Wrangler uses, so a Node.js dev server reads the same KV keys and D1 rows. With a custom Wrangler path, note that Wrangler appends `v3` and `getPlatformProxy` does not, so `wrangler dev --persist-to ./dev-data` pairs with `persist: { path: "./dev-data/v3" }`. - **Local Explorer** (Wrangler 4.118 or later): while `wrangler dev` runs, pressing `e` opens `/cdn-cgi/local/explorer`, a browser view for inspecting and editing the local KV, D1 and R2 data, among other bindings. ## What interviewers probe - Local data is real data on disk: it persists, can be inspected, and must not be committed. - A seeding command and the dev server only share data when they agree on the path, which is the usual cause of "I seeded it but the Worker cannot see it". - The Wrangler 4 change to local-by-default for `kv key` and `r2 object` commands, which reverses old muscle memory.

  • How do you give a Durable Object local test data, given there is no CLI command for it?
    Through the Worker itself: add a development-only route, or a script that calls the running dev server, which gets the object's stub and calls a method that writes the state. For classes declared with `new_sqlite_classes`, Local Explorer can also insert rows directly. The object stores it under `.wrangler/state` like any other binding, so it survives restarts until you delete that folder or the class's subfolder.
  • Why might a seeding script written for Wrangler 3 now leave production unchanged?
    Wrangler 3's `wrangler kv key put` and `wrangler r2 object put` wrote to the deployed resource unless given `--local`. Wrangler 4 reversed the default to local storage, so the same command silently edits `.wrangler/state`. Adding `--remote` restores the old target; being explicit with `--local` or `--remote` in scripts avoids the ambiguity.

  • Believes local KV and D1 data live in memory and vanish when wrangler dev stops.
  • Expects wrangler dev to remember a --persist-to path between runs.
  • Seeds KV with --local but without the --persist-to path the dev server uses.
  • Assumes wrangler kv key put still targets the deployed namespace by default in Wrangler 4.
  • Commits the .wrangler folder so teammates share test data.

Assumes Wrangler 4.149: since Wrangler 4.0 the wrangler kv key and wrangler r2 object commands default to local storage (Wrangler 3 defaulted to the deployed resource), and local state sits under .wrangler/state/v3.