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

petebacondarwin · 2025-07-10T10:50:02Z

Fixes #9394

TODO

docs changes:
escape hatch for i.e. Next (which load .env file using a different mechanism)
added CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV opt-out env var

Tests
- Tests included
- Tests not necessary because:
Public documentation
- Cloudflare docs PR(s): Document the new .env support for local development cloudflare-docs#23837
- Documentation not necessary because:
Wrangler V3 Backport
- Wrangler PR:
- Not necessary because: New feature

changeset-bot · 2025-07-10T10:50:06Z

🦋 Changeset detected

Latest commit: 7ec7a0c

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

This PR includes changesets to release 3 packages

Name	Type
@cloudflare/vite-plugin	Major
wrangler	Minor
@cloudflare/vitest-pool-workers	Patch

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

pkg-pr-new · 2025-07-10T10:52:35Z

create-cloudflare

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

@cloudflare/kv-asset-handler

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

miniflare

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

@cloudflare/pages-shared

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

@cloudflare/unenv-preset

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

@cloudflare/vite-plugin

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

@cloudflare/vitest-pool-workers

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

@cloudflare/workers-editor-shared

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

wrangler

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

commit: 7ec7a0c

packages/wrangler/e2e/__snapshots__/dev.test.ts.snap

packages/wrangler/e2e/helpers/wrangler.ts

packages/wrangler/src/__tests__/dev.test.ts

packages/wrangler/src/__tests__/helpers/run-wrangler.ts

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

When step-through debugging you can often get stuck on this bit of code, where there is an unhandled rejection in the body reading code. It is not apparent in real life and has no effect outside of debugging.

- use mockfile in config-changes test - each test in this file expects a starting condition but needs to wait for Vite to be ready since it might be rebooting.

- only listen for one config change before restarting - abort extra restarts

This reverts commit 4523114.

jamesopstad

Great work persevering Pete!

A couple of general comments in addition to those inline:

A lot more of the tests now wrap expect in waitUntil. As I understand it each test file should now get its own Miniflare instance so this shouldn't be necessary unless the tests cause the dev server to restart. Is that incorrect?
There is now a requirement for tests that use page to call page.goto(viteTestUrl) manually at the start of each test. I think that's OK but just something we'll have to watch out for as tests in the same file now continue from the previous test's state.
If we're going to start including debug logs then I think we could do this more generally and use specifiers like Vite does. Not for this PR but might be nice to follow up using the approach here.
Generally, I'm most concerned about how much code has been added and that it makes reading the source more challenging. If there's any room for now stripping back some of the changes that have been made then that would be good.
For posterity, it would be really helpful if you could add a comment to this PR summarising what the issues were and how they've been resolved.

jamesopstad · 2025-07-30T09:13:06Z

packages/vite-plugin-cloudflare/playground/vitest-setup.ts

 				}
 			} else {
-				await startDefaultServe();
+				server = await startDefaultServe();


Why set this here when it's set in startDefaultServe()?

Good point. I think at this stage I was being overly conservative since I wasn't sure whether the startDefaultServe() was mutating things correctly. Arguably it shouldn't mutate server at all.

jamesopstad · 2025-07-30T09:26:37Z

packages/vite-plugin-cloudflare/src/index.ts

+				// It is possible to get into a situation where the dev server is restarted by a config file change
+				// right in the middle of the Vite server and the supporting Workers being initialized.
+				// We use an abort controller to signal to the initialization code that it should stop if the config has changed.
+				const restartAbortController = new AbortController();


It would be good to establish if this is still necessary with all the other changes as it makes the code quite a bit more complex.

Yes, we should rip this out if it is not needed

jamesopstad · 2025-07-30T09:28:38Z

packages/vite-plugin-cloudflare/src/index.ts

+								"Restarting dev server and aborting previous setup"
+							);
+							restartAbortController.abort();
+							await viteDevServer.watcher.close();


Is this needed when using watcher.once()?

I just realised that watcher.once() is incorrect, since it will be triggered by lots of other file changes.
I meant to revert that and just remove the watcher if we are reverting.
It happens to work in the tests because we don't touch any other files.

jamesopstad · 2025-07-30T09:29:50Z

packages/vite-plugin-cloudflare/src/index.ts

+					debuglog(configId, "Waiting for Miniflare to be ready before update");
+					await miniflare.ready;
+					debuglog(configId, "Updating the Miniflare instance");
 					await miniflare.setOptions(miniflareDevOptions);
+					debuglog(configId, "Waiting for Miniflare to be ready after update");
+					await miniflare.ready;
+					debuglog(configId, "Miniflare is ready");


Can you explain why await miniflare.ready is needed in these two places?

It's probably not. I was just chucking stuff in there to see if waiting for things helps.

packages/vite-plugin-cloudflare/src/index.ts

jamesopstad · 2025-07-30T09:33:42Z

packages/vite-plugin-cloudflare/src/index.ts

+				// We use a `configId` to help debug how the config changes are triggering the restarts.
+				const configId = randomUUID();


Creating this value and passing it around has added a lot of code. Do we still need it now that you've resolved the issues?

Avoid the `server` variable being global and mutated

petebacondarwin · 2025-07-30T10:29:02Z

Fixes attempted that should be checked and reverted if not necessary:

remove beforeEach(() => page.goto()) from vitest-setup.ts and apply it where needed at the start of tests
- this was because this hook often crashed with a ERRCONNREFUSED error that I couldn't use vi.waitFor() nor simply catch in the hook as that then caused other tests to fail
- refactor: add page.goto() back into beforeEach #10140
run await miniflare.ready all over the place
- probably not needed any more
- refactor: remove unnecessary miniflare.ready awaits #10135
add abort signal code to avoid running initRunners()
- this was the original fix attempt but doesn't necessarily help if the problem is across tests
- refactor: remove abort controller from vite-plugin #10137
replace poolOptions: { forks: { singleFork: true } }withfileParallelism: false`
- this is actually probably a solid part of the fix
use of debuglog() all over the place for diagnosing the failures
- could try switching to the Vite equivalent (e.g. createDebugger())
add await viteDevServer.watcher.close(); to the watch handler
- almost definitely not needed now that it has a watcher.off()
- refactor: remove redundant watcher.close() from vite-plugin #10138

workers-devprod added this to workers-sdk Jul 10, 2025

github-project-automation bot moved this to Untriaged in workers-sdk Jul 10, 2025

petebacondarwin force-pushed the pbd/wrangler/dotenv branch 3 times, most recently from 9efb7bb to 9c3ff21 Compare July 10, 2025 16:32