feat(wrangler): Support disabling state persistence in unstable_startWorker() (cloudflare#12815)

Co-authored-by: James Opstad <13586373+jamesopstad@users.noreply.github.com>
Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: 3 people

.changeset/kind-socks-beam.md

@@ -0,0 +1,26 @@
+---
+"wrangler": minor
+---
+
+Support disabling persistence in `unstable_startWorker()` and `unstable_dev()`
+
+You can now disable persistence entirely by setting `persist: false` in the `dev` options:
+
+```typescript
+const worker = await unstable_dev("./src/worker.ts", {
+	persist: false,
+});
+```
+
+Or when using `unstable_startWorker()`:
+
+```typescript
+const worker = await unstable_startWorker({
+	entrypoint: "./src/worker.ts",
+	dev: {
+		persist: false,
+	},
+});
+```
+
+This is useful for testing scenarios where you want to ensure a clean state on each run without any persisted data from previous runs.

packages/wrangler/src/__tests__/api/startDevWorker/LocalRuntimeController.test.ts

@@ -733,6 +733,74 @@ describe("LocalRuntimeController", () => {
 			res = await fetch(urlFromParts(event.proxyData.userWorkerUrl));
 			expect(await res.text()).toBe("miss");
 		});
+		it("should not persist data when persist is false", async () => {
+			const bus = new FakeBus();
+			const controller = new LocalRuntimeController(bus);
+			teardown(() => controller.teardown());
+
+			const config = {
+				dev: {
+					persist: false,
+				},
+				entrypoint: "NOT_REAL",
+				name: "worker",
+			} satisfies Partial<StartDevWorkerOptions>;
+
+			const bundle = makeEsbuildBundle(dedent/*javascript*/ `
+				export default {
+					async fetch(request, env, ctx) {
+						const key = "http://localhost/";
+						if (request.method === "POST") {
+							const response = new Response("cached", {
+								headers: {
+									"Cache-Control": "max-age=3600"
+								}
+							});
+							await caches.default.put(key, response);
+						}
+						return (await caches.default.match(key)) ?? new Response("miss");
+					}
+				}`);
+
+			controller.onBundleStart({
+				config: configDefaults(config),
+				type: "bundleStart",
+			});
+
+			controller.onBundleComplete({
+				bundle,
+				config: configDefaults(config),
+				type: "bundleComplete",
+			});
+
+			let event = await bus.waitFor("reloadComplete");
+			let res = await fetch(urlFromParts(event.proxyData.userWorkerUrl), {
+				method: "POST",
+			});
+			expect(await res.text()).toBe("cached");
+
+			// Check that data is cached within the same session
+			res = await fetch(urlFromParts(event.proxyData.userWorkerUrl));
+			expect(await res.text()).toBe("cached");
+
+			// Restart the worker - data should NOT be persisted since persist is false
+			await controller.teardown();
+			controller.onBundleStart({
+				config: configDefaults(config),
+				type: "bundleStart",
+			});
+			controller.onBundleComplete({
+				bundle,
+				config: configDefaults(config),
+				type: "bundleComplete",
+			});
+
+			event = await bus.waitFor("reloadComplete");
+			res = await fetch(urlFromParts(event.proxyData.userWorkerUrl));
+
+			// Data should be gone since persistence was disabled
+			expect(await res.text()).toBe("miss");
+		});
 		it("should expose KV namespace bindings", async () => {
 			const bus = new FakeBus();
 			const controller = new LocalRuntimeController(bus);

packages/wrangler/src/__tests__/dev/get-local-persistence-path.test.ts

@@ -0,0 +1,64 @@
+import path from "node:path";
+import { describe, it } from "vitest";
+import { getLocalPersistencePath } from "../../dev/get-local-persistence-path";
+import { runInTempDir } from "../helpers/run-in-tmp";
+import type { Config } from "@cloudflare/workers-utils";
+
+function makeConfig(userConfigPath?: string): Config {
+	return {
+		userConfigPath,
+	} as Config;
+}
+
+describe("getLocalPersistencePath", () => {
+	runInTempDir();
+
+	describe("when persistence is disabled", () => {
+		it("should return `false` when `persistTo` is `false`", ({ expect }) => {
+			const result = getLocalPersistencePath(false, makeConfig());
+			expect(result).toBe(false);
+		});
+	});
+
+	describe("when persistence is enabled with default path", () => {
+		it("should return `.wrangler/state` relative to cwd when no config path", ({
+			expect,
+		}) => {
+			const result = getLocalPersistencePath(undefined, makeConfig());
+			expect(result).toBe(path.resolve(process.cwd(), ".wrangler/state"));
+		});
+
+		it("should return `.wrangler/state` relative to config file directory", ({
+			expect,
+		}) => {
+			const configPath = "/some/project/wrangler.json";
+			const result = getLocalPersistencePath(undefined, makeConfig(configPath));
+			expect(result).toBe(path.resolve("/some/project", ".wrangler/state"));
+		});
+	});
+
+	describe("when persistence path is explicitly specified", () => {
+		it("should resolve relative path from cwd", ({ expect }) => {
+			const result = getLocalPersistencePath("./custom-persist", makeConfig());
+			expect(result).toBe(path.resolve(process.cwd(), "./custom-persist"));
+		});
+
+		it("should resolve absolute path from cwd", ({ expect }) => {
+			const absolutePath = "/absolute/persist/path";
+			const result = getLocalPersistencePath(absolutePath, makeConfig());
+			expect(result).toBe(path.resolve(process.cwd(), absolutePath));
+		});
+
+		it("should resolve relative path from cwd even when config path is set", ({
+			expect,
+		}) => {
+			// When a custom persistTo is specified, it's always relative to cwd, not config path
+			const configPath = "/some/project/wrangler.json";
+			const result = getLocalPersistencePath(
+				"./custom-persist",
+				makeConfig(configPath)
+			);
+			expect(result).toBe(path.resolve(process.cwd(), "./custom-persist"));
+		});
+	});
+});

packages/wrangler/src/api/startDevWorker/types.ts

@@ -145,8 +145,8 @@ export interface StartDevWorkerInput {
 		remote?: boolean | "minimal";
 		/** Cloudflare Account credentials. Can be provided upfront or as a function which will be called only when required. */
 		auth?: AsyncHook<CfAccount, [Pick<Config, "account_id">]>; // provide config.account_id as a hook param
-		/** Whether local storage (KV, Durable Objects, R2, D1, etc) is persisted. You can also specify the directory to persist data to. */
-		persist?: string;
+		/** Whether local storage (KV, Durable Objects, R2, D1, etc) is persisted. You can also specify the directory to persist data to. Set to `false` to disable persistence. */
+		persist?: string | false;
 		/** Controls which logs are logged 🤙. */
 		logLevel?: LogLevel;
 		/** Whether the worker server restarts upon source/config file changes. */
@@ -202,7 +202,7 @@ export interface StartDevWorkerInput {
 
 export type StartDevWorkerOptions = Omit<
 	StartDevWorkerInput,
-	"assets" | "containers"
+	"assets" | "containers" | "dev"
 > & {
 	/** A worker's directory. Usually where the Wrangler configuration file is located */
 	projectRoot: string;
@@ -221,7 +221,7 @@ export type StartDevWorkerOptions = Omit<
 		site?: Config["site"];
 	};
 	dev: StartDevWorkerInput["dev"] & {
-		persist: string;
+		persist: string | false;
 		auth?: AsyncHook<CfAccount>; // redefine without config.account_id hook param (can only be provided by ConfigController with access to the Wrangler configuration file, not by other controllers eg RemoteRuntimeContoller)
 	};
 	entrypoint: string;

packages/wrangler/src/dev.ts

@@ -356,6 +356,8 @@ export type StartDevOptions = DevArguments &
 		enableIpc?: boolean;
 		dockerPath?: string;
 		containerEngine?: string;
+		/** Set to `false` to disable persistence. When `true` or `undefined`, uses default persistence path. */
+		persist?: boolean;
 	};
 
 export async function getHostAndRoutes(

packages/wrangler/src/dev/get-local-persistence-path.ts

@@ -6,11 +6,34 @@ import type { Config } from "@cloudflare/workers-utils";
  *
  * We use the `userConfigPath` rather than the potentially redirected `configPath`
  * to decide the path to this directory.
+ *
+ * @param persistTo - The path to persist to, or `false` to disable persistence, or `undefined` to use the default path.
+ *
+ * @returns The path to persist to, or `false` if persistence is disabled.
  */
+export function getLocalPersistencePath(
+	persistTo: false,
+	config: Config
+): false;
+
 export function getLocalPersistencePath(
 	persistTo: string | undefined,
+	config: Config
+): string;
+
+export function getLocalPersistencePath(
+	persistTo: string | false | undefined,
+	config: Config
+): string | false;
+
+export function getLocalPersistencePath(
+	persistTo: string | false | undefined,
 	{ userConfigPath }: Config
-) {
+): string | false {
+	if (persistTo === false) {
+		return false;
+	}
+
 	return persistTo
 		? // If path specified, always treat it as relative to cwd()
 			path.resolve(process.cwd(), persistTo)

packages/wrangler/src/dev/miniflare/index.ts

@@ -80,7 +80,7 @@ export interface ConfigBundle {
 	rules: Config["rules"];
 	inspectorPort: number | undefined;
 	inspectorHost: string | undefined;
-	localPersistencePath: string | null;
+	localPersistencePath: string | false;
 	liveReload: boolean;
 	crons: Config["triggers"]["crons"];
 	queueConsumers: Config["queues"]["consumers"];
@@ -883,7 +883,7 @@ export function buildMiniflareBindingOptions(
 export function getDefaultPersistRoot(
 	localPersistencePath: ConfigBundle["localPersistencePath"]
 ): string | undefined {
-	if (localPersistencePath !== null) {
+	if (localPersistencePath !== false) {
 		const v3Path = path.join(localPersistencePath, "v3");
 		return v3Path;
 	}

packages/wrangler/src/dev/start-dev.ts

@@ -257,7 +257,7 @@ async function setupDevEnv(
 							? undefined
 							: args.upstreamProtocol === "https",
 				},
-				persist: args.persistTo,
+				persist: args.persist === false ? false : args.persistTo,
 				liveReload: args.liveReload,
 				testScheduled: args.testScheduled,
 				logLevel: args.logLevel,