refactor: migrate wrangler dev to use Miniflare dev registry #10245

edmundhung · 2025-08-06T12:18:17Z

This PR fully replaces Wrangler's dev registry setup with the Miniflare implementation, paving the way for dev registry support in multi-config mode in a later PR (#10354).

Notable changes:

Removes a large amount of logic from buildMiniflareBindingOptions, since Miniflare now handles this directly. As a result, Wrangler no longer updates the Miniflare config when the dev registry changes, because address resolution now happens in real time within Miniflare's proxy server.
Removes Wrangler's dev registry implementation. Instead, it imports getWorkerRegistry from Miniflare to populate the connection status when printing the bindings table, and sets up a callback in Miniflare to re-print the table when the dev registry updates.
Fixes tail handler support over the dev registry in wrangler dev when static assets are enabled.

Tests
- Tests included
- Tests not necessary because:
Public documentation
- Cloudflare docs PR(s):
- Documentation not necessary because: no user facing changes, internal refactor only
Wrangler V3 Backport
- Wrangler PR:
- Not necessary because: Miniflare dev registry is v4 only

changeset-bot · 2025-08-06T12:18:21Z

🦋 Changeset detected

Latest commit: 64b0ce4

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

This PR includes changesets to release 3 packages

Name	Type
wrangler	Patch
@cloudflare/vite-plugin	Patch
@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-08-06T12:20:41Z

create-cloudflare

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

@cloudflare/kv-asset-handler

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

miniflare

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

@cloudflare/pages-shared

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

@cloudflare/unenv-preset

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

@cloudflare/vite-plugin

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

@cloudflare/vitest-pool-workers

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

@cloudflare/workers-editor-shared

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

wrangler

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

commit: 64b0ce4

packages/miniflare/src/shared/dev-registry.worker.ts

edmundhung · 2025-08-13T12:07:02Z

fixtures/entrypoints-rpc-tests/tests/entrypoints.spec.ts

+		await waitFor(async () => {
+			let response = await fetch(url);
+			expect(response.status).toBe(503);
+			expect(await response.text()).toBe(
+				'Couldn\'t find a local dev session for the "ThingEntrypoint" entrypoint of service "bound" to proxy to'


The Miniflare dev registry is less precise here, since it cannot distinguish between a worker that is registered without the required entrypoint and one that is not registered at all.

I believe this logic mainly exists to support older Wrangler versions before JSRPC was introduced early last year, so it should be safe to drop for now?

I agree—I don't think we need to support Wrangler v3 to v4 dev registry connections

edmundhung · 2025-08-13T12:08:36Z

fixtures/entrypoints-rpc-tests/tests/entrypoints.spec.ts

-	test("should throw if binding to version of wrangler without entrypoints support over HTTPS", async ({
-		dev,
-		isolatedDevRegistryPath,
-	}) => {
-		// Start entry worker first, so the server starts with a stubbed service not
-		// found binding
-		const { url, session } = await dev({
-			"wrangler.toml": dedent`
-			name = "entry"
-			main = "index.ts"
-
-			[[services]]
-			binding = "SERVICE"
-			service = "bound"
-		`,
-			"index.ts": dedent`
-			export default {
-				async fetch(request, env, ctx) {
-					return env.SERVICE.fetch("http://placeholder/");
-				}
-			}
-		`,
-		});
-		let response = await fetch(url);
-		expect(await response.text()).toBe(
-			'[wrangler] Couldn\'t find `wrangler dev` session for service "bound" to proxy to'
-		);
-
-		await writeFile(
-			path.join(isolatedDevRegistryPath, "bound"),
-			JSON.stringify({
-				protocol: "https",
-				mode: "local",
-				port: 0,
-				host: "localhost",
-				durableObjects: [],
-				durableObjectsHost: "localhost",
-				durableObjectsPort: 0,
-				// Intentionally omitting `entrypointAddresses`
-			})
-		);
-
-		// Wait for error to be thrown
-		await waitFor(() => {
-			const output = session.getOutput();
-			expect(output).toMatch(
-				'Cannot proxy to `wrangler dev` session for service "bound" because it uses HTTPS. Please upgrade "bound"\'s `wrangler` version, or remove the `--local-protocol`/`dev.local_protocol` option.'
-			);
-		});
-	});


This test is removed as the miniflare dev registry does support HTTPS (#10281)

Can we change this to be a test that passes with https configured? Why do we need to remove it?

Added the test back in b12d326 and it now passes with https configured

edmundhung · 2025-08-13T12:09:34Z

packages/miniflare/src/index.ts

 	type WorkerRegistry,
 	type WorkerDefinition,
 	getDefaultDevRegistryPath,
+	getWorkerRegistry,


We export this method for Wrangler to read the worker registry for printing the bindings table before miniflare startup.

edmundhung · 2025-08-13T12:10:09Z

packages/miniflare/src/shared/external-service.ts

 									const message = ${
 										isProxyEnabled
-											? `\`Cannot access "\${key}" as Durable Object RPC is not yet supported between multiple dev sessions.\``
+											? `\`Cannot access "\${className}#\${key}" as Durable Object RPC is not yet supported between multiple dev sessions.\``


Minor improvement to include the class name in the error message.
e.g. Cannot access "MyDurableObject#ping" as Durable Object RPC is not yet supported between multiple dev sessions.

edmundhung · 2025-08-13T12:12:57Z

packages/miniflare/src/workers/assets/rpc-proxy.worker.ts

+	tail(events: TraceItem[]) {
+		// Temporary workaround: the tail events is not serializable over capnproto yet
+		// But they are effectively JSON, so we are serializing them to JSON and parsing it back to make it transferable.
+		// @ts-expect-error FIXME when https://github.com/cloudflare/workerd/pull/4595 lands
+		return this.env.USER_WORKER.tail(
+			JSON.parse(JSON.stringify(events, tailEventsReplacer), tailEventsReviver)
+		);
+	}


This fixes tail handler support over the dev registry in wrangler dev when static assets are enabled.

github-actions · 2025-08-13T20:17:04Z

Failed to automatically backport this PR's changes to Wrangler v3. Please manually create a PR targeting the v3-maintenance branch with your changes. Thank you for helping us keep Wrangler v3 supported!

Depending on your changes, running git rebase --onto v3-maintenance main edmundhung/DEVX-2124 might be a good starting point.

Notes:

your PR branch should be named v3-backport-10245
add the skip-v3-pr label to the current PR to stop this workflow from failing

edmundhung · 2025-08-14T11:13:41Z

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

+						name,
+						{
+							className,
+							scriptName,


Before this change, we skipped passing scriptName here likely because we consider those to be external DO which would be handled by the dev registry. But that means wrangler dev multi configs mode doesn't support scriptName. This fixes that.

penalosa

Fantastic work! 🎉

penalosa · 2025-08-14T14:36:39Z

fixtures/entrypoints-rpc-tests/tests/entrypoints.spec.ts

+		await waitFor(async () => {
+			let response = await fetch(url);
+			expect(response.status).toBe(503);
+			expect(await response.text()).toBe(
+				'Couldn\'t find a local dev session for the "ThingEntrypoint" entrypoint of service "bound" to proxy to'


I agree—I don't think we need to support Wrangler v3 to v4 dev registry connections

penalosa · 2025-08-14T14:37:25Z

fixtures/entrypoints-rpc-tests/tests/entrypoints.spec.ts

-	test("should throw if binding to version of wrangler without entrypoints support over HTTPS", async ({
-		dev,
-		isolatedDevRegistryPath,
-	}) => {
-		// Start entry worker first, so the server starts with a stubbed service not
-		// found binding
-		const { url, session } = await dev({
-			"wrangler.toml": dedent`
-			name = "entry"
-			main = "index.ts"
-
-			[[services]]
-			binding = "SERVICE"
-			service = "bound"
-		`,
-			"index.ts": dedent`
-			export default {
-				async fetch(request, env, ctx) {
-					return env.SERVICE.fetch("http://placeholder/");
-				}
-			}
-		`,
-		});
-		let response = await fetch(url);
-		expect(await response.text()).toBe(
-			'[wrangler] Couldn\'t find `wrangler dev` session for service "bound" to proxy to'
-		);
-
-		await writeFile(
-			path.join(isolatedDevRegistryPath, "bound"),
-			JSON.stringify({
-				protocol: "https",
-				mode: "local",
-				port: 0,
-				host: "localhost",
-				durableObjects: [],
-				durableObjectsHost: "localhost",
-				durableObjectsPort: 0,
-				// Intentionally omitting `entrypointAddresses`
-			})
-		);
-
-		// Wait for error to be thrown
-		await waitFor(() => {
-			const output = session.getOutput();
-			expect(output).toMatch(
-				'Cannot proxy to `wrangler dev` session for service "bound" because it uses HTTPS. Please upgrade "bound"\'s `wrangler` version, or remove the `--local-protocol`/`dev.local_protocol` option.'
-			);
-		});
-	});


Can we change this to be a test that passes with https configured? Why do we need to remove it?

penalosa · 2025-08-14T14:40:54Z

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

 		// absolute resolved path
 		persist: localPersistencePath,
-		registry: input.dev?.registry,
+		registryPath: input.dev?.registryPath,


Do we need to rename this? We have other fileds in this object that are paths but aren't named with the suffix Path (i.e. persist above)

removed the path suffix in 2835b62

penalosa · 2025-08-14T14:44:04Z

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

 	bindings: CfWorkerInit["bindings"];
 	migrations: Config["migrations"] | undefined;
-	workerDefinitions: WorkerRegistry | undefined | null;
+	devRegistryPath: string | undefined;


As above—can we just call this registry or devRegistry?

Named it devRegistry in 2835b62

workers-devprod added this to workers-sdk Aug 6, 2025

github-project-automation bot moved this to Untriaged in workers-sdk Aug 6, 2025

edmundhung force-pushed the edmundhung/DEVX-2124 branch 2 times, most recently from 3bc942f to 106e326 Compare August 6, 2025 17:15

edmundhung changed the base branch from main to edmundhung/DEVX-2122 August 6, 2025 19:57

edmundhung force-pushed the edmundhung/DEVX-2122 branch from 4418341 to bedb0c5 Compare August 7, 2025 16:00

Base automatically changed from edmundhung/DEVX-2122 to main August 7, 2025 19:02

edmundhung force-pushed the edmundhung/DEVX-2124 branch from 88d833f to 3355a10 Compare August 8, 2025 11:10

github-advanced-security bot found potential problems Aug 8, 2025

View reviewed changes

packages/miniflare/src/shared/dev-registry.worker.ts Fixed Show fixed Hide fixed

edmundhung force-pushed the edmundhung/DEVX-2124 branch 3 times, most recently from b85c6e3 to 1ab8411 Compare August 11, 2025 15:26

edmundhung changed the base branch from main to edmundhung/improve-dev-registry-tests August 11, 2025 15:27

edmundhung force-pushed the edmundhung/DEVX-2124 branch 2 times, most recently from dc25544 to f00e3e2 Compare August 12, 2025 14:45

Base automatically changed from edmundhung/improve-dev-registry-tests to main August 13, 2025 10:18

edmundhung mentioned this pull request Aug 13, 2025

feat(miniflare): add unsafeHandleDevRegistryUpdate callback option #10349

Merged

6 tasks

edmundhung force-pushed the edmundhung/DEVX-2124 branch from 3936d04 to c30afed Compare August 13, 2025 10:38

edmundhung changed the base branch from main to edmundhung/registry-update-callback August 13, 2025 10:39

edmundhung force-pushed the edmundhung/DEVX-2124 branch from c30afed to db72fd8 Compare August 13, 2025 10:59

edmundhung changed the title ~~refactor(wrangler): switch single worker dev to use miniflare dev registry implementation~~ refactor: migrate wrangler dev to use Miniflare dev registry Aug 13, 2025

edmundhung force-pushed the edmundhung/DEVX-2124 branch from db72fd8 to 9c876ab Compare August 13, 2025 11:55

edmundhung commented Aug 13, 2025

View reviewed changes

edmundhung marked this pull request as ready for review August 13, 2025 14:18

edmundhung requested a review from a team as a code owner August 13, 2025 14:19

edmundhung requested review from penalosa and petebacondarwin August 13, 2025 14:19

Base automatically changed from edmundhung/registry-update-callback to main August 13, 2025 20:03

refactor: migrate wrangler dev to use Miniflare dev registry

17f74f7

edmundhung force-pushed the edmundhung/DEVX-2124 branch from 9c876ab to 17f74f7 Compare August 13, 2025 20:15

edmundhung added the skip-v3-pr Skip validation of presence of a v3 backport PR label Aug 13, 2025

edmundhung commented Aug 14, 2025

View reviewed changes

fixup! refactor: migrate wrangler dev to use Miniflare dev registry

dd1d78b

penalosa approved these changes Aug 14, 2025

View reviewed changes

github-project-automation bot moved this from Untriaged to Approved in workers-sdk Aug 14, 2025

edmundhung added 4 commits August 15, 2025 15:45

unremove test

b12d326

rename option from registryPath to registry

2835b62

fix message in tests

3aaf64b

fix message again

02dfaf7

edmundhung force-pushed the edmundhung/DEVX-2124 branch from f9b0355 to 02dfaf7 Compare August 18, 2025 16:24

edmundhung added 2 commits August 18, 2025 21:30

fix vectorize worker name having invalid characters on window

39312d2

accept test tail events coming in different orders

64b0ce4

edmundhung merged commit d304055 into main Aug 19, 2025
31 checks passed

github-project-automation bot moved this from Approved to Done in workers-sdk Aug 19, 2025

edmundhung deleted the edmundhung/DEVX-2124 branch August 19, 2025 10:55

workers-devprod mentioned this pull request Aug 19, 2025

Version Packages #10406

Merged

refactor: migrate wrangler dev to use Miniflare dev registry #10245

refactor: migrate wrangler dev to use Miniflare dev registry #10245

Uh oh!

Conversation

edmundhung commented Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new bot commented Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

edmundhung Aug 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Aug 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

penalosa left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

edmundhung commented Aug 6, 2025 •

edited

Loading

changeset-bot bot commented Aug 6, 2025 •

edited

Loading

pkg-pr-new bot commented Aug 6, 2025 •

edited

Loading

edmundhung Aug 13, 2025 •

edited

Loading