feat(wrangler): Support disabling state persistence in unstable_startWorker()

[NuroDev]

Fixes #3652.

As mentioned in the issue above, a nice QoL improvement would be having the ability to disable persistence entirely, which is especially helpful when running tests. This change adds support to both startWorker() and unstable_dev() to be able to set the persist option to false or null.

Note

This only applies to state persistence. .wrangler/tmp will still be required for module bundling.

---

• Tests
  • Tests included/updated
  • Automated tests not possible - manual testing has been completed as follows:
  • Additional testing not necessary because:
• Public documentation
  • Cloudflare docs PR(s):
  • Documentation not necessary because: startWorker() is still marked as "unstable" in the docs so individual property documentation has not been added yet.

A picture of a cute animal (not mandatory, but encouraged)

---

[github-actions]

✅ All changesets look good

[pkg-pr-new]

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@12815

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@12815

miniflare

npm i https://pkg.pr.new/miniflare@12815

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@12815

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@12815

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@12815

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@12815

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@12815

wrangler

npm i https://pkg.pr.new/wrangler@12815

commit: 34b6ae0

[ask-bonk]

OK so it's re-exported as unstable_startWorker in cli.ts:68. The changeset name is correct.

Now let me think about whether there are any actual issues with this PR:

1. Type correctness: The flow is sound. false | null → getLocalPersistencePath returns null → Miniflare gets undefined for defaultPersistRoot → in-memory storage. Correct.

2. Overload signatures: Clean and type-safe. Existing callers that pass string | undefined get back string (never null). New callers passing false | null get back null.

3. Test coverage: Tests cover both the getLocalPersistencePath function directly and the LocalRuntimeController integration with persist: null.

4. unstable_dev path: The persist?: boolean field already existed on Unstable_DevOptions (line 30). The new persist?: boolean on StartDevOptions (line 368) mirrors it. start-dev.ts:260 bridges them correctly: args.persist === false ? false : args.persistTo.

5. Backward compatibility: The input type changes from persist?: string to persist?: string | false | null. This is purely additive — existing callers passing string | undefined continue to work identically.

6. One potential concern: The Unstable_DevOptions.persist (line 30 of api/dev.ts) was already boolean before this PR. But the new StartDevOptions.persist is also boolean. When persist is true (not just undefined), the code at start-dev.ts:260 does args.persist === false ? false : args.persistTo. If persist is true and persistTo is undefined, this passes undefined to StartDevWorkerInput.dev.persist, which defaults to the .wrangler/state path. That's the correct behavior for persist: true.

7. The Unstable_DevOptions.persist comment says "Enable persistence for local mode" — but unstable_dev has had persistence enabled by default for a while. Setting persist: true is a no-op (same as undefined). Setting persist: false now actually disables it. This is fine and consistent with the existing API shape.

Everything looks correct. The types, the runtime behavior, the tests, and the changeset all align properly. The implementation is clean and handles all edge cases.

LGTM

github run

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[changeset-bot]

🦋 Changeset detected

Latest commit: 0adc313

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[workers-devprod]

Codeowners approval required for this PR:

• ✅ @cloudflare/wrangler

Show detailed file reviewers

[petebacondarwin]

Can we ditch the null option and just have string|false?
I think that would be clearer for the user, and simpler to implement.