[miniflare] Add environment variables to control cf.json fetching

Adds two new environment variables that allow users to control the cf.json
caching behavior in Miniflare:

- CLOUDFLARE_CF_FETCH_ENABLED: Set to "false" or "0" to disable fetching
  entirely (uses fallback data). Defaults to "true".
- CLOUDFLARE_CF_FETCH_PATH: Set to a custom path to use a different location
  for caching the cf.json file. Empty string is treated as unset.

This is useful for non-JavaScript projects (like Rust or Go Workers)
that don't want a node_modules directory created automatically.

Fixes #3659

Author: petebacondarwin

.changeset/add-wrangler-cf-fetch-env.md

@@ -0,0 +1,24 @@
+---
+"miniflare": minor
+---
+
+Add environment variables to control cf.json fetching behavior
+
+You can now use environment variables to control how Miniflare handles the `Request.cf` object caching:
+
+- `CLOUDFLARE_CF_FETCH_ENABLED` - Set to "false" to disable fetching entirely and use fallback data. No `node_modules/.mf/cf.json` file will be created. Defaults to "true".
+- `CLOUDFLARE_CF_FETCH_PATH` - Set to a custom path to use a different location for caching the cf.json file instead of the default `node_modules/.mf/cf.json`.
+
+This is particularly useful for non-JavaScript projects (like Rust or Go Workers) that don't want a `node_modules` directory created automatically.
+
+Example:
+
+```sh
+# Disable cf fetching for all projects
+export CLOUDFLARE_CF_FETCH_ENABLED=false
+npx wrangler dev
+
+# Or use a custom cache location
+export CLOUDFLARE_CF_FETCH_PATH=/tmp/.cf-cache.json
+npx wrangler dev
+```

packages/miniflare/src/cf.ts

@@ -10,6 +10,10 @@ import type { IncomingRequestCfProperties } from "@cloudflare/workers-types/expe
 const defaultCfPath = path.resolve("node_modules", ".mf", "cf.json");
 const defaultCfFetchEndpoint = "https://workers.cloudflare.com/cf.json";
 
+// Environment variable names for controlling cf fetch behavior
+const CF_FETCH_ENABLED_ENV_VAR = "CLOUDFLARE_CF_FETCH_ENABLED";
+const CF_FETCH_PATH_ENV_VAR = "CLOUDFLARE_CF_FETCH_PATH";
+
 export const fallbackCf: IncomingRequestCfProperties = {
 	asOrganization: "",
 	asn: 395747,
@@ -67,21 +71,82 @@ export const CF_DAYS = 30;
 
 type CoreOptions = OptionalZodTypeOf<Plugins["core"]["sharedOptions"]>;
 
+/**
+ * Check if cf fetching is disabled via environment variable.
+ *
+ * Returns true if CLOUDFLARE_CF_FETCH_ENABLED is set to "false".
+ */
+function isCfFetchDisabledByEnv(): boolean {
+	const envValue = process.env[CF_FETCH_ENABLED_ENV_VAR];
+	if (envValue === undefined) {
+		return false;
+	}
+	return envValue.toLowerCase() === "false";
+}
+
+/**
+ * Get custom cf.json path from environment variable.
+ *
+ * Returns the path if CLOUDFLARE_CF_FETCH_PATH is set and non-empty, otherwise undefined.
+ */
+function getCfPathFromEnv(): string | undefined {
+	const envValue = process.env[CF_FETCH_PATH_ENV_VAR];
+	// Treat empty string as unset (use default path)
+	if (envValue === undefined || envValue === "") {
+		return undefined;
+	}
+	return envValue;
+}
+
+/**
+ * Get the cf option value, considering environment variable overrides.
+ *
+ * Priority:
+ * 1. If `cf` option is explicitly provided (not undefined), use it
+ * 2. Check CLOUDFLARE_CF_FETCH_ENABLED environment variable:
+ *    - "false" -> return false (disable fetching)
+ * 3. Check CLOUDFLARE_CF_FETCH_PATH environment variable:
+ *    - If set, use as custom path for cf.json cache
+ * 4. Return undefined to use default behavior
+ */
+function getCfOptionWithEnvOverride(cf: CoreOptions["cf"]): CoreOptions["cf"] {
+	// If cf option is explicitly provided, use it
+	if (cf !== undefined) {
+		return cf;
+	}
+
+	// Check if fetching is disabled
+	if (isCfFetchDisabledByEnv()) {
+		return false;
+	}
+
+	// Check for custom path
+	const customPath = getCfPathFromEnv();
+	if (customPath !== undefined) {
+		return customPath;
+	}
+
+	return undefined;
+}
+
 export async function setupCf(
 	log: Log,
 	cf: CoreOptions["cf"]
-): Promise<Record<string, any>> {
-	if (!(cf ?? process.env.NODE_ENV !== "test")) {
+): Promise<Record<string, unknown>> {
+	// Apply environment variable override
+	const effectiveCf = getCfOptionWithEnvOverride(cf);
+
+	if (!(effectiveCf ?? process.env.NODE_ENV !== "test")) {
 		return fallbackCf;
 	}
 
-	if (typeof cf === "object") {
-		return cf;
+	if (typeof effectiveCf === "object") {
+		return effectiveCf;
 	}
 
 	let cfPath = defaultCfPath;
-	if (typeof cf === "string") {
-		cfPath = cf;
+	if (typeof effectiveCf === "string") {
+		cfPath = effectiveCf;
 	}
 
 	// Try load cfPath, if this fails, we'll catch the error and refetch.

packages/miniflare/test/cf.spec.ts

@@ -0,0 +1,139 @@
+import { Miniflare } from "miniflare";
+import { afterEach, beforeEach, describe, test } from "vitest";
+import { useDispose } from "./test-shared";
+
+describe("CLOUDFLARE_CF_FETCH_ENABLED environment variable", () => {
+	let originalEnabledEnv: string | undefined;
+	let originalPathEnv: string | undefined;
+
+	beforeEach(() => {
+		originalEnabledEnv = process.env.CLOUDFLARE_CF_FETCH_ENABLED;
+		originalPathEnv = process.env.CLOUDFLARE_CF_FETCH_PATH;
+	});
+
+	afterEach(() => {
+		if (originalEnabledEnv === undefined) {
+			delete process.env.CLOUDFLARE_CF_FETCH_ENABLED;
+		} else {
+			process.env.CLOUDFLARE_CF_FETCH_ENABLED = originalEnabledEnv;
+		}
+		if (originalPathEnv === undefined) {
+			delete process.env.CLOUDFLARE_CF_FETCH_PATH;
+		} else {
+			process.env.CLOUDFLARE_CF_FETCH_PATH = originalPathEnv;
+		}
+	});
+
+	test("CLOUDFLARE_CF_FETCH_ENABLED=false disables cf fetching", async ({
+		expect,
+	}) => {
+		process.env.CLOUDFLARE_CF_FETCH_ENABLED = "false";
+
+		const mf = new Miniflare({
+			script: "",
+			modules: true,
+		});
+		useDispose(mf);
+
+		const cf = await mf.getCf();
+		// Should return fallback cf object when fetching is disabled
+		expect(cf).toMatchObject({
+			colo: "DFW",
+			country: "US",
+		});
+	});
+
+	test("CLOUDFLARE_CF_FETCH_ENABLED=FALSE (uppercase) disables cf fetching", async ({
+		expect,
+	}) => {
+		process.env.CLOUDFLARE_CF_FETCH_ENABLED = "FALSE";
+
+		const mf = new Miniflare({
+			script: "",
+			modules: true,
+		});
+		useDispose(mf);
+
+		const cf = await mf.getCf();
+		// Should return fallback cf object when fetching is disabled
+		expect(cf).toMatchObject({
+			colo: "DFW",
+			country: "US",
+		});
+	});
+
+	test("explicit cf option takes precedence over CLOUDFLARE_CF_FETCH_ENABLED", async ({
+		expect,
+	}) => {
+		process.env.CLOUDFLARE_CF_FETCH_ENABLED = "false";
+
+		const mf = new Miniflare({
+			script: "",
+			modules: true,
+			cf: { colo: "CUSTOM", country: "GB" },
+		});
+		useDispose(mf);
+
+		const cf = await mf.getCf();
+		// Explicit cf option should take precedence
+		expect(cf).toEqual({ colo: "CUSTOM", country: "GB" });
+	});
+
+	test("explicit cf option takes precedence over CLOUDFLARE_CF_FETCH_PATH", async ({
+		expect,
+	}) => {
+		process.env.CLOUDFLARE_CF_FETCH_PATH = "/some/custom/path.json";
+
+		const mf = new Miniflare({
+			script: "",
+			modules: true,
+			cf: { colo: "CUSTOM", country: "GB" },
+		});
+		useDispose(mf);
+
+		const cf = await mf.getCf();
+		// Explicit cf option should take precedence
+		expect(cf).toEqual({ colo: "CUSTOM", country: "GB" });
+	});
+
+	test("CLOUDFLARE_CF_FETCH_ENABLED takes precedence over CLOUDFLARE_CF_FETCH_PATH when disabled", async ({
+		expect,
+	}) => {
+		process.env.CLOUDFLARE_CF_FETCH_ENABLED = "false";
+		process.env.CLOUDFLARE_CF_FETCH_PATH = "/some/custom/path.json";
+
+		const mf = new Miniflare({
+			script: "",
+			modules: true,
+		});
+		useDispose(mf);
+
+		const cf = await mf.getCf();
+		// Should return fallback cf object when fetching is disabled, ignoring the path
+		expect(cf).toMatchObject({
+			colo: "DFW",
+			country: "US",
+		});
+	});
+
+	test("empty CLOUDFLARE_CF_FETCH_PATH uses default path", async ({
+		expect,
+	}) => {
+		// Setting to empty string should be treated as unset (use default behavior)
+		process.env.CLOUDFLARE_CF_FETCH_PATH = "";
+
+		const mf = new Miniflare({
+			script: "",
+			modules: true,
+		});
+		useDispose(mf);
+
+		const cf = await mf.getCf();
+		// Should return fallback cf object (default test behavior)
+		// This verifies empty string doesn't cause issues and uses default path
+		expect(cf).toMatchObject({
+			colo: "DFW",
+			country: "US",
+		});
+	});
+});

packages/workers-utils/src/environment-variables/factory.ts

@@ -24,6 +24,10 @@ type VariableNames =
 
 	// ## Development & Local Testing
 
+	/** Controls whether to fetch the cf.json file. Set to "false" or "0" to disable fetching and use fallback data. Defaults to "true". */
+	| "CLOUDFLARE_CF_FETCH_ENABLED"
+	/** Custom path for caching the cf.json file. Overrides the default node_modules/.mf/cf.json location. */
+	| "CLOUDFLARE_CF_FETCH_PATH"
 	/** Local database connection strings for Hyperdrive development. The * should be replaced with the Hyperdrive binding name in the Worker. */
 	| `CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_${string}`
 	/** Suppress Hyperdrive-related warnings during development. */

packages/workers-utils/src/environment-variables/misc-variables.ts

@@ -346,3 +346,40 @@ export const getLocalExplorerEnabledFromEnv =
 		variableName: "X_LOCAL_EXPLORER",
 		defaultValue: false,
 	});
+
+/**
+ * `CLOUDFLARE_CF_FETCH_ENABLED` controls whether Miniflare fetches the `cf.json` file
+ * containing request.cf properties from workers.cloudflare.com.
+ *
+ * - If set to "false", disables fetching and uses fallback data (no files created)
+ * - If set to "true" or not set, uses the default behavior (fetches and caches cf.json)
+ *
+ * This is particularly useful for non-JavaScript projects that don't want
+ * a node_modules directory created automatically.
+ *
+ * Example:
+ * ```sh
+ * # Disable cf fetching entirely
+ * CLOUDFLARE_CF_FETCH_ENABLED=false npx wrangler dev
+ * ```
+ */
+export const getCfFetchEnabledFromEnv = getBooleanEnvironmentVariableFactory({
+	variableName: "CLOUDFLARE_CF_FETCH_ENABLED",
+	defaultValue: true,
+});
+
+/**
+ * `CLOUDFLARE_CF_FETCH_PATH` specifies a custom path for caching the cf.json file.
+ *
+ * - If set, uses the specified path instead of the default node_modules/.mf/cf.json
+ * - If not set, uses the default location (node_modules/.mf/cf.json)
+ *
+ * Example:
+ * ```sh
+ * # Use a custom cache location
+ * CLOUDFLARE_CF_FETCH_PATH=/tmp/cf-cache.json npx wrangler dev
+ * ```
+ */
+export const getCfFetchPathFromEnv = getEnvironmentVariableFactory({
+	variableName: "CLOUDFLARE_CF_FETCH_PATH",
+});