feat: introduce defaultPersistRoot option (#9330)

edmundhung · petebacondarwin · web-flow · commit 34c71ce9208f · 2025-05-23T17:24:05.000Z
* feat: introduce defaultPersistRoot option

* add changeset

* Update packages/miniflare/src/plugins/shared/index.ts

Co-authored-by: Pete Bacon Darwin &lt;pete@bacondarwin.com&gt;

* add missin
g getPersistPath on secret store plugin

* fix format error

---------

Co-authored-by: Pete Bacon Darwin &lt;pete@bacondarwin.com&gt;
diff --git a/.changeset/blue-streets-thank.md b/.changeset/blue-streets-thank.md
@@ -0,0 +1,24 @@
+---
+"miniflare": minor
+---
+
+Add a new `defaultPersistRoot` option to control where plugins persist data when no path is provided.
+
+```js
+// Before this change / No `defaultPersistRoot`
+new Miniflare({
+	kvPersist: undefined, // → "/(tmp)/kv"
+	d1Persist: true, // → "/.mf/d1"
+	r2Persist: false, // → "/(tmp)/d1"
+	cachePersist: "/my-cache", // → "/my-cache"
+});
+
+// With `defaultPersistRoot`
+new Miniflare({
+	defaultPersistRoot: "/storage",
+	kvPersist: undefined, // → "/storage/kv"
+	d1Persist: true, // → "/storage/d1"
+	r2Persist: false, // → "/(tmp)/d1"
+	cachePersist: "/my-cache", // → "/my-cache"
+});
+```
diff --git a/.changeset/twenty-cats-clap.md b/.changeset/twenty-cats-clap.md
@@ -0,0 +1,6 @@
+---
+"@cloudflare/vite-plugin": minor
+"wrangler": minor
+---
+
+Updated internal configuration to use Miniflare’s new `defaultPersistRoot` instead of per-plugin `persist` flags
diff --git a/packages/miniflare/src/index.ts b/packages/miniflare/src/index.ts
@@ -1293,6 +1293,7 @@ export class Miniflare {
 				workerIndex: i,
 				additionalModules,
 				tmpPath: this.#tmpPath,
+				defaultPersistRoot: sharedOpts.core.defaultPersistRoot,
 				workerNames,
 				loopbackPort,
 				unsafeStickyBlobs,
diff --git a/packages/miniflare/src/plugins/cache/index.ts b/packages/miniflare/src/plugins/cache/index.ts
@@ -56,6 +56,7 @@ export const CACHE_PLUGIN: Plugin<
 		options,
 		workerIndex,
 		tmpPath,
+		defaultPersistRoot,
 		unsafeStickyBlobs,
 	}) {
 		const cache = options.cache ?? true;
@@ -100,7 +101,12 @@ export const CACHE_PLUGIN: Plugin<
 			const uniqueKey = `miniflare-${CACHE_OBJECT_CLASS_NAME}`;
 
 			const persist = sharedOptions.cachePersist;
-			const persistPath = getPersistPath(CACHE_PLUGIN_NAME, tmpPath, persist);
+			const persistPath = getPersistPath(
+				CACHE_PLUGIN_NAME,
+				tmpPath,
+				defaultPersistRoot,
+				persist
+			);
 			await fs.mkdir(persistPath, { recursive: true });
 			const storageService: Service = {
 				name: CACHE_STORAGE_SERVICE_NAME,
@@ -148,6 +154,6 @@ export const CACHE_PLUGIN: Plugin<
 		return services;
 	},
 	getPersistPath({ cachePersist }, tmpPath) {
-		return getPersistPath(CACHE_PLUGIN_NAME, tmpPath, cachePersist);
+		return getPersistPath(CACHE_PLUGIN_NAME, tmpPath, undefined, cachePersist);
 	},
 };
diff --git a/packages/miniflare/src/plugins/core/index.ts b/packages/miniflare/src/plugins/core/index.ts
@@ -226,6 +226,10 @@ export const CoreSharedOptionsSchema = z.object({
 	unsafeTriggerHandlers: z.boolean().optional(),
 	// Enable logging requests
 	logRequests: z.boolean().default(true),
+
+	// Path to the root directory for persisting data
+	// Used as the default for all plugins with the plugin name as the subdirectory name
+	defaultPersistRoot: z.string().optional(),
 });
 
 export const CORE_PLUGIN_NAME = "core";
diff --git a/packages/miniflare/src/plugins/d1/index.ts b/packages/miniflare/src/plugins/d1/index.ts
@@ -99,6 +99,7 @@ export const D1_PLUGIN: Plugin<
 		options,
 		sharedOptions,
 		tmpPath,
+		defaultPersistRoot,
 		log,
 		unsafeStickyBlobs,
 	}) {
@@ -115,7 +116,12 @@ export const D1_PLUGIN: Plugin<
 
 		if (databases.length > 0) {
 			const uniqueKey = `miniflare-${D1_DATABASE_OBJECT_CLASS_NAME}`;
-			const persistPath = getPersistPath(D1_PLUGIN_NAME, tmpPath, persist);
+			const persistPath = getPersistPath(
+				D1_PLUGIN_NAME,
+				tmpPath,
+				defaultPersistRoot,
+				persist
+			);
 			await fs.mkdir(persistPath, { recursive: true });
 
 			const storageService: Service = {
@@ -165,6 +171,6 @@ export const D1_PLUGIN: Plugin<
 		return services;
 	},
 	getPersistPath({ d1Persist }, tmpPath) {
-		return getPersistPath(D1_PLUGIN_NAME, tmpPath, d1Persist);
+		return getPersistPath(D1_PLUGIN_NAME, tmpPath, undefined, d1Persist);
 	},
 };
diff --git a/packages/miniflare/src/plugins/do/index.ts b/packages/miniflare/src/plugins/do/index.ts
@@ -103,6 +103,7 @@ export const DURABLE_OBJECTS_PLUGIN: Plugin<
 	async getServices({
 		sharedOptions,
 		tmpPath,
+		defaultPersistRoot,
 		durableObjectClassNames,
 		unsafeEphemeralDurableObjects,
 	}) {
@@ -125,6 +126,7 @@ export const DURABLE_OBJECTS_PLUGIN: Plugin<
 		const storagePath = getPersistPath(
 			DURABLE_OBJECTS_PLUGIN_NAME,
 			tmpPath,
+			defaultPersistRoot,
 			sharedOptions.durableObjectsPersist
 		);
 		// `workerd` requires the `disk.path` to exist. Setting `recursive: true`
@@ -145,6 +147,7 @@ export const DURABLE_OBJECTS_PLUGIN: Plugin<
 		return getPersistPath(
 			DURABLE_OBJECTS_PLUGIN_NAME,
 			tmpPath,
+			undefined,
 			durableObjectsPersist
 		);
 	},
diff --git a/packages/miniflare/src/plugins/kv/index.ts b/packages/miniflare/src/plugins/kv/index.ts
@@ -106,6 +106,7 @@ export const KV_PLUGIN: Plugin<
 		options,
 		sharedOptions,
 		tmpPath,
+		defaultPersistRoot,
 		log,
 		unsafeStickyBlobs,
 	}) {
@@ -122,7 +123,12 @@ export const KV_PLUGIN: Plugin<
 
 		if (services.length > 0) {
 			const uniqueKey = `miniflare-${KV_NAMESPACE_OBJECT_CLASS_NAME}`;
-			const persistPath = getPersistPath(KV_PLUGIN_NAME, tmpPath, persist);
+			const persistPath = getPersistPath(
+				KV_PLUGIN_NAME,
+				tmpPath,
+				defaultPersistRoot,
+				persist
+			);
 			await fs.mkdir(persistPath, { recursive: true });
 			const storageService: Service = {
 				name: KV_STORAGE_SERVICE_NAME,
@@ -178,7 +184,7 @@ export const KV_PLUGIN: Plugin<
 	},
 
 	getPersistPath({ kvPersist }, tmpPath) {
-		return getPersistPath(KV_PLUGIN_NAME, tmpPath, kvPersist);
+		return getPersistPath(KV_PLUGIN_NAME, tmpPath, undefined, kvPersist);
 	},
 };
 
diff --git a/packages/miniflare/src/plugins/r2/index.ts b/packages/miniflare/src/plugins/r2/index.ts
@@ -74,6 +74,7 @@ export const R2_PLUGIN: Plugin<
 		options,
 		sharedOptions,
 		tmpPath,
+		defaultPersistRoot,
 		log,
 		unsafeStickyBlobs,
 	}) {
@@ -90,7 +91,12 @@ export const R2_PLUGIN: Plugin<
 
 		if (buckets.length > 0) {
 			const uniqueKey = `miniflare-${R2_BUCKET_OBJECT_CLASS_NAME}`;
-			const persistPath = getPersistPath(R2_PLUGIN_NAME, tmpPath, persist);
+			const persistPath = getPersistPath(
+				R2_PLUGIN_NAME,
+				tmpPath,
+				defaultPersistRoot,
+				persist
+			);
 			await fs.mkdir(persistPath, { recursive: true });
 			const storageService: Service = {
 				name: R2_STORAGE_SERVICE_NAME,
@@ -139,6 +145,6 @@ export const R2_PLUGIN: Plugin<
 		return services;
 	},
 	getPersistPath({ r2Persist }, tmpPath) {
-		return getPersistPath(R2_PLUGIN_NAME, tmpPath, r2Persist);
+		return getPersistPath(R2_PLUGIN_NAME, tmpPath, undefined, r2Persist);
 	},
 };
diff --git a/packages/miniflare/src/plugins/secret-store/index.ts b/packages/miniflare/src/plugins/secret-store/index.ts
@@ -67,7 +67,13 @@ export const SECRET_STORE_PLUGIN: Plugin<
 			])
 		);
 	},
-	async getServices({ options, sharedOptions, tmpPath, unsafeStickyBlobs }) {
+	async getServices({
+		options,
+		sharedOptions,
+		tmpPath,
+		defaultPersistRoot,
+		unsafeStickyBlobs,
+	}) {
 		const configs = options.secretsStoreSecrets
 			? Object.values(options.secretsStoreSecrets)
 			: [];
@@ -79,6 +85,7 @@ export const SECRET_STORE_PLUGIN: Plugin<
 		const persistPath = getPersistPath(
 			SECRET_STORE_PLUGIN_NAME,
 			tmpPath,
+			defaultPersistRoot,
 			sharedOptions.secretsStorePersist
 		);
 
@@ -162,4 +169,12 @@ export const SECRET_STORE_PLUGIN: Plugin<
 
 		return [...services, storageService, objectService];
 	},
+	getPersistPath({ secretsStorePersist }, tmpPath) {
+		return getPersistPath(
+			SECRET_STORE_PLUGIN_NAME,
+			tmpPath,
+			undefined,
+			secretsStorePersist
+		);
+	},
 };
diff --git a/packages/miniflare/src/plugins/shared/index.ts b/packages/miniflare/src/plugins/shared/index.ts
@@ -71,6 +71,7 @@ export interface PluginServicesOptions<
 	workerIndex: number;
 	additionalModules: Worker_Module[];
 	tmpPath: string;
+	defaultPersistRoot: string | undefined;
 	workerNames: string[];
 	loopbackPort: number;
 	unsafeStickyBlobs: boolean;
@@ -182,6 +183,7 @@ export function maybeParseURL(url: Persistence): URL | undefined {
 export function getPersistPath(
 	pluginName: string,
 	tmpPath: string,
+	defaultPersistRoot: string | undefined,
 	persist: Persistence
 ): string {
 	// If persistence is disabled, use "memory" storage. Note we're still
@@ -191,10 +193,17 @@ export function getPersistPath(
 	// keep Miniflare 2's behaviour, so persist to a temporary path which we
 	// destroy on `dispose()`.
 	const memoryishPath = path.join(tmpPath, pluginName);
-	if (persist === undefined || persist === false) {
+	if (persist === false) {
 		return memoryishPath;
 	}
 
+	// If `persist` is undefined, use either the default path or fallback to the tmpPath
+	if (persist === undefined) {
+		return defaultPersistRoot === undefined
+			? memoryishPath
+			: path.join(defaultPersistRoot, pluginName);
+	}
+
 	// Try parse `persist` as a URL
 	const url = maybeParseURL(persist);
 	if (url !== undefined) {
@@ -211,7 +220,7 @@ export function getPersistPath(
 
 	// Otherwise, fallback to file storage
 	return persist === true
-		? path.join(DEFAULT_PERSIST_ROOT, pluginName)
+		? path.join(defaultPersistRoot ?? DEFAULT_PERSIST_ROOT, pluginName)
 		: persist;
 }
 
diff --git a/packages/miniflare/src/plugins/workflows/index.ts b/packages/miniflare/src/plugins/workflows/index.ts
@@ -59,10 +59,11 @@ export const WORKFLOWS_PLUGIN: Plugin<
 		);
 	},
 
-	async getServices({ options, sharedOptions, tmpPath }) {
+	async getServices({ options, sharedOptions, tmpPath, defaultPersistRoot }) {
 		const persistPath = getPersistPath(
 			WORKFLOWS_PLUGIN_NAME,
 			tmpPath,
+			defaultPersistRoot,
 			sharedOptions.workflowsPersist
 		);
 		await fs.mkdir(persistPath, { recursive: true });
@@ -130,6 +131,11 @@ export const WORKFLOWS_PLUGIN: Plugin<
 	},
 
 	getPersistPath({ workflowsPersist }, tmpPath) {
-		return getPersistPath(WORKFLOWS_PLUGIN_NAME, tmpPath, workflowsPersist);
+		return getPersistPath(
+			WORKFLOWS_PLUGIN_NAME,
+			tmpPath,
+			undefined,
+			workflowsPersist
+		);
 	},
 };
diff --git a/packages/vite-plugin-cloudflare/src/miniflare-options.ts b/packages/vite-plugin-cloudflare/src/miniflare-options.ts
@@ -30,22 +30,12 @@ import type { MiniflareOptions, SharedOptions, WorkerOptions } from "miniflare";
 import type { FetchFunctionOptions } from "vite/module-runner";
 import type { SourcelessWorkerOptions, Unstable_Config } from "wrangler";
 
-type PersistOptions = Pick<
-	SharedOptions,
-	| "cachePersist"
-	| "d1Persist"
-	| "durableObjectsPersist"
-	| "kvPersist"
-	| "r2Persist"
-	| "workflowsPersist"
->;
-
-function getPersistence(
+function getPersistenceRoot(
 	root: string,
 	persistState: PersistState
-): PersistOptions {
+): string | undefined {
 	if (persistState === false) {
-		return {};
+		return;
 	}
 
 	const defaultPersistPath = ".wrangler/state";
@@ -55,14 +45,7 @@ function getPersistence(
 		"v3"
 	);
 
-	return {
-		cachePersist: path.join(persistPath, "cache"),
-		d1Persist: path.join(persistPath, "d1"),
-		durableObjectsPersist: path.join(persistPath, "do"),
-		kvPersist: path.join(persistPath, "kv"),
-		r2Persist: path.join(persistPath, "r2"),
-		workflowsPersist: path.join(persistPath, "workflows"),
-	};
+	return persistPath;
 }
 
 function missingWorkerErrorMessage(workerName: string) {
@@ -416,7 +399,7 @@ export function getDevMiniflareOptions(
 				logger.logWithLevel(LogLevel.ERROR, decoder.decode(error))
 			);
 		},
-		...getPersistence(
+		defaultPersistRoot: getPersistenceRoot(
 			resolvedViteConfig.root,
 			resolvedPluginConfig.persistState
 		),
@@ -614,7 +597,10 @@ export function getPreviewMiniflareOptions(
 				logger.logWithLevel(LogLevel.ERROR, decoder.decode(error))
 			);
 		},
-		...getPersistence(resolvedViteConfig.root, persistState),
+		defaultPersistRoot: getPersistenceRoot(
+			resolvedViteConfig.root,
+			persistState
+		),
 		workers,
 	};
 }
diff --git a/packages/wrangler/src/api/integrations/platform/index.ts b/packages/wrangler/src/api/integrations/platform/index.ts
diff --git a/packages/wrangler/src/dev/miniflare.ts b/packages/wrangler/src/dev/miniflare.ts
diff --git a/packages/wrangler/src/kv/helpers.ts b/packages/wrangler/src/kv/helpers.ts
diff --git a/packages/wrangler/src/r2/helpers.ts b/packages/wrangler/src/r2/helpers.ts
diff --git a/packages/wrangler/src/secrets-store/commands.ts b/packages/wrangler/src/secrets-store/commands.ts
