Add support for reading .env files as runtime vars in local development

.changeset/moody-breads-pump.md

@@ -0,0 +1,20 @@
+---
+"@cloudflare/vite-plugin": minor
+"wrangler": minor
+---
+
+Add support for loading local dev vars from .env files
+
+If there are no `.dev.vars` or `.dev.vars.<environment>` files, when running Wrangler or the Vite plugin in local development mode,
+they will now try to load additional local dev vars from `.env`, `.env.local`, `.env.<environment>` and `.env.<environment>.local` files.
+
+These loaded vars are only for local development and have no effect in production to the vars in a deployed Worker.
+Wrangler and Vite will continue to load `.env` files in order to configure themselves as a tool.
+
+Further details:
+
+- In `vite build` the local vars will be computed and stored in a `.dev.vars` file next to the compiled Worker code, so that `vite preview` can use them.
+- The `wrangler types` command will similarly read the `.env` files (if no `.dev.vars` files) in order to generate the `Env` interface.
+- If the `CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV` environment variable is `"false"` then local dev variables will not be loaded from `.env` files.
+- If the `CLOUDFLARE_INCLUDE_PROCESS_ENV` environment variable is `"true"` then all the environment variables found on `process.env` will be included as local dev vars.
+- Wrangler (but not Vite plugin) also now supports the `--env-file=<path/to/dotenv/file>` global CLI option. This affects both loading `.env` to configure Wrangler the tool as well as loading local dev vars.

.github/workflows/test-and-check.yml

@@ -168,6 +168,7 @@ jobs:
           WRANGLER_LOG_PATH: ${{ runner.temp }}/wrangler-debug-logs/
           TEST_REPORT_PATH: ${{ runner.temp }}/test-report/index.html
           CI_OS: ${{ matrix.description }}
+          NODE_DEBUG: "@cloudflare:vite-plugin"
 
       - name: Upload turbo logs
         if: always()

fixtures/nodejs-hybrid-app/.env

@@ -0,0 +1 @@
+DEV_VAR_FROM_DOT_ENV="dev-var-from-dot-env"

fixtures/nodejs-hybrid-app/.gitignore

@@ -0,0 +1 @@
+!.env

fixtures/nodejs-hybrid-app/src/index.ts

@@ -22,6 +22,10 @@ export default {
 				return testGetRandomValues();
 			case "/test-process":
 				return testProcessBehavior();
+			case "/env":
+				return Response.json(env);
+			case "/process-env":
+				return Response.json(process.env);
 			case "/query":
 				return testPostgresLibrary(env, ctx);
 			case "/test-x509-certificate":

fixtures/nodejs-hybrid-app/tests/index.test.ts

@@ -88,4 +88,22 @@ describe("nodejs compat", () => {
 		const response = await fetch(`http://${ip}:${port}/test-http`);
 		await expect(response.text()).resolves.toBe("OK");
 	});
+
+	test("process.env contains vars", async ({ expect }) => {
+		const { ip, port } = wrangler;
+		const response = await fetch(`http://${ip}:${port}/process-env`);
+		await expect(response.json()).resolves.toMatchObject({
+			DB_HOSTNAME: "hh-pgsql-public.ebi.ac.uk",
+			DEV_VAR_FROM_DOT_ENV: "dev-var-from-dot-env",
+		});
+	});
+
+	test("env contains vars", async ({ expect }) => {
+		const { ip, port } = wrangler;
+		const response = await fetch(`http://${ip}:${port}/env`);
+		await expect(response.json()).resolves.toMatchObject({
+			DB_HOSTNAME: "hh-pgsql-public.ebi.ac.uk",
+			DEV_VAR_FROM_DOT_ENV: "dev-var-from-dot-env",
+		});
+	});
 });

fixtures/nodejs-hybrid-app/wrangler.jsonc

@@ -1,8 +1,9 @@
 {
 	"name": "nodejs-hybrid-app",
 	"main": "src/index.ts",
-	// Setting compat date to 2024/09/23 means we don't need to use `nodejs_compat_v2`
-	"compatibility_date": "2024-09-23",
+	// Setting compat date after 2024/09/23 means we don't need to use `nodejs_compat_v2`
+	// Setting compat date after 2025/04/01 means we don't need to use `nodejs_compat_populate_process_env`
+	"compatibility_date": "2025-07-01",
 	"compatibility_flags": ["nodejs_compat"],
 	/*
     These DB connection values are to a public database containing information about

fixtures/pages-workerjs-app/.env

@@ -0,0 +1 @@
+FOO=bar

fixtures/pages-workerjs-app/.gitignore

@@ -0,0 +1 @@
+!.env

fixtures/pages-workerjs-app/package.json

@@ -4,7 +4,7 @@
 	"sideEffects": false,
 	"scripts": {
 		"check:type": "tsc",
-		"dev": "wrangler pages dev ./workerjs-test --port 8792",
+		"dev": "wrangler pages dev ./workerjs-test --port 8792 --compatibility-date=2025-07-15",
 		"test:ci": "vitest run",
 		"test:watch": "vitest",
 		"type:tests": "tsc -p ./tests/tsconfig.json"

fixtures/pages-workerjs-app/tests/index.test.ts

@@ -35,7 +35,12 @@ describe("Pages _worker.js", () => {
 		const { ip, port, stop } = await runWranglerPagesDev(
 			resolve(__dirname, ".."),
 			"./workerjs-test",
-			["--no-bundle=false", "--port=0", "--inspector-port=0"]
+			[
+				"--no-bundle=false",
+				"--port=0",
+				"--inspector-port=0",
+				"--compatibility-date=2025-07-15",
+			]
 		);
 		try {
 			await expect(
@@ -52,7 +57,12 @@ describe("Pages _worker.js", () => {
 		const { ip, port, stop } = await runWranglerPagesDev(
 			resolve(__dirname, ".."),
 			"./workerjs-test",
-			["--bundle", "--port=0", "--inspector-port=0"]
+			[
+				"--bundle",
+				"--port=0",
+				"--inspector-port=0",
+				"--compatibility-date=2025-07-15",
+			]
 		);
 		try {
 			await expect(
@@ -71,8 +81,9 @@ describe("Pages _worker.js", () => {
 			await runWranglerPagesDev(resolve(__dirname, ".."), "./workerjs-test", [
 				"--port=0",
 				"--inspector-port=0",
+				"--compatibility-date=2025-07-15",
 			]);
-		vi.waitFor(
+		await vi.waitFor(
 			() => {
 				expect(getOutput()).toContain("Ready on");
 			},
@@ -118,7 +129,7 @@ describe("Pages _worker.js", () => {
 				"--port=0",
 				"--inspector-port=0",
 			]);
-		vi.waitFor(
+		await vi.waitFor(
 			() => {
 				expect(getOutput()).toContain("Ready on");
 			},
@@ -157,6 +168,22 @@ describe("Pages _worker.js", () => {
 		}
 	});
 
+	// Serendipitously, this .env reading also works for `wrangler pages dev`.
+	it("should read local dev vars from the .env file", async ({ expect }) => {
+		const { ip, port, stop } = await runWranglerPagesDev(
+			resolve(__dirname, ".."),
+			"./workerjs-test",
+			["--port=0", "--inspector-port=0", "--compatibility-date=2025-07-15"]
+		);
+		try {
+			const response = await fetch(`http://${ip}:${port}/env`);
+			const env = (await response.json()) as { FOO: string };
+			expect(env.FOO).toBe("bar");
+		} finally {
+			await stop();
+		}
+	});
+
 	async function tryRename(
 		basePath: string,
 		from: string,

fixtures/pages-workerjs-app/workerjs-test/_worker.js

@@ -1,7 +1,11 @@
 import text from "./other-script";
 
 export default {
-	async fetch() {
-		return new Response(text);
+	async fetch(request, env) {
+		if (request.url.endsWith("/env")) {
+			return Response.json(env);
+		} else {
+			return new Response(text);
+		}
 	},
 };

fixtures/worker-app/.env

@@ -0,0 +1 @@
+FOO=bar

fixtures/worker-app/.gitignore

@@ -1 +1,2 @@
 dist
+!.env

fixtures/worker-app/src/index.js

@@ -25,6 +25,7 @@ export default {
 		const { pathname, origin, hostname, host } = new URL(request.url);
 		if (pathname.startsWith("/fav"))
 			return new Response("Not found", { status: 404 });
+		if (pathname === "/env") return Response.json(env.FOO);
 		if (pathname === "/version_metadata") return Response.json(env.METADATA);
 		if (pathname === "/random") return new Response(hexEncode(randomBytes(8)));
 		if (pathname === "/error") throw new Error("Oops!");

fixtures/worker-app/tests/index.test.ts

@@ -203,4 +203,10 @@ describe("'wrangler dev' correctly renders pages", () => {
 			]
 		`);
 	});
+
+	it("reads local dev vars from the .env file", async ({ expect }) => {
+		const response = await fetch(`http://${ip}:${port}/env`);
+		const env = await response.text();
+		expect(env).toBe(`"bar"`);
+	});
 });

packages/miniflare/src/index.ts

@@ -776,56 +776,6 @@ export function _transformsForContentEncodingAndContentType(
 	return encoders;
 }
 
-async function writeResponse(response: Response, res: http.ServerResponse) {
-	// Convert headers into Node-friendly format
-	const headers: http.OutgoingHttpHeaders = {};
-	for (const entry of response.headers) {
-		const key = entry[0].toLowerCase();
-		const value = entry[1];
-		if (key === "set-cookie") {
-			headers[key] = response.headers.getSetCookie();
-		} else {
-			headers[key] = value;
-		}
-	}
-
-	// If a `Content-Encoding` header is set, we'll need to encode the body
-	// (likely only set by custom service bindings)
-	const encoding = headers["content-encoding"]?.toString();
-	const type = headers["content-type"]?.toString();
-	const encoders = _transformsForContentEncodingAndContentType(encoding, type);
-	if (encoders.length > 0) {
-		// `Content-Length` if set, will be wrong as it's for the decoded length
-		delete headers["content-length"];
-	}
-
-	res.writeHead(response.status, response.statusText, headers);
-
-	// `initialStream` is the stream we'll write the response to. It
-	// should end up as the first encoder, piping to the next encoder,
-	// and finally piping to the response:
-	//
-	// encoders[0] (initialStream) -> encoders[1] -> res
-	//
-	// Not using `pipeline(passThrough, ...encoders, res)` here as that
-	// gives a premature close error with server sent events. This also
-	// avoids creating an extra stream even when we're not encoding.
-	let initialStream: Writable = res;
-	for (let i = encoders.length - 1; i >= 0; i--) {
-		encoders[i].pipe(initialStream);
-		initialStream = encoders[i];
-	}
-
-	// Response body may be null if empty
-	if (response.body) {
-		for await (const chunk of response.body) {
-			if (chunk) initialStream.write(chunk);
-		}
-	}
-
-	initialStream.end();
-}
-
 function safeReadableStreamFrom(iterable: AsyncIterable<Uint8Array>) {
 	// Adapted from `undici`, catches errors from `next()` to avoid unhandled
 	// rejections from aborted request body streams:
@@ -1344,7 +1294,7 @@ export class Miniflare {
 				res.writeHead(404);
 				res.end();
 			} else {
-				await writeResponse(response, res);
+				await this.#writeResponse(response, res);
 			}
 		}
 
@@ -1402,7 +1352,7 @@ export class Miniflare {
 		}
 
 		// Otherwise, send the response as is (e.g. unauthorised)
-		await writeResponse(response, res);
+		await this.#writeResponse(response, res);
 	};
 
 	#handleLoopbackConnect = async (
@@ -1508,6 +1458,65 @@ export class Miniflare {
 		});
 	};
 
+	async #writeResponse(response: Response, res: http.ServerResponse) {
+		// Convert headers into Node-friendly format
+		const headers: http.OutgoingHttpHeaders = {};
+		for (const entry of response.headers) {
+			const key = entry[0].toLowerCase();
+			const value = entry[1];
+			if (key === "set-cookie") {
+				headers[key] = response.headers.getSetCookie();
+			} else {
+				headers[key] = value;
+			}
+		}
+
+		// If a `Content-Encoding` header is set, we'll need to encode the body
+		// (likely only set by custom service bindings)
+		const encoding = headers["content-encoding"]?.toString();
+		const type = headers["content-type"]?.toString();
+		const encoders = _transformsForContentEncodingAndContentType(
+			encoding,
+			type
+		);
+		if (encoders.length > 0) {
+			// `Content-Length` if set, will be wrong as it's for the decoded length
+			delete headers["content-length"];
+		}
+
+		res.writeHead(response.status, response.statusText, headers);
+
+		// `initialStream` is the stream we'll write the response to. It
+		// should end up as the first encoder, piping to the next encoder,
+		// and finally piping to the response:
+		//
+		// encoders[0] (initialStream) -> encoders[1] -> res
+		//
+		// Not using `pipeline(passThrough, ...encoders, res)` here as that
+		// gives a premature close error with server sent events. This also
+		// avoids creating an extra stream even when we're not encoding.
+		let initialStream: Writable = res;
+		for (let i = encoders.length - 1; i >= 0; i--) {
+			encoders[i].pipe(initialStream);
+			initialStream = encoders[i];
+		}
+
+		// Response body may be null if empty
+		if (response.body) {
+			try {
+				for await (const chunk of response.body) {
+					if (chunk) initialStream.write(chunk);
+				}
+			} catch (error) {
+				this.#log.debug(
+					`Error writing response body, closing response early: ${error}`
+				);
+			}
+		}
+
+		initialStream.end();
+	}
+
 	async #getLoopbackPort(): Promise<number> {
 		// This function must be run with `#runtimeMutex` held