Support `ctx.exports` in the Vite plugin #11238

jamesopstad · 2025-11-11T15:40:45Z

Fixes #000.

ctx.exports is now supported in the runtime (see https://developers.cloudflare.com/workers/runtime-apis/context/#exports). In vite dev, the user's Worker entry module is not the top-level module that workerd sees. Instead the top-level module exports proxy classes that interface with Vite to fetch the user's code. Because of this, ctx.exports would not automatically work as the exports to include in this module can not be determined from the user's config. We now run the code in the user's Worker entry module when starting the dev server to determine the exports that should be included.

Summary

Initial server start

Miniflare is started and the Worker entry modules are populated with exports derived from the user's Worker config files (across all Workers).
A request is made to the Workers to get the export names and types for the exports defined in the user's Worker entry modules.
The exports types are compared to those that were used when starting Miniflare. If they differ then Miniflare is restarted.

Note that restarting the Vite dev server itself is not possible during the initial start as the server has not yet been fully initialised. Restarting Miniflare is therefore the better option during this phase and is more optimal.

Updates to Worker entry modules

When a Worker entry module is updated, a message is sent to the dev server with the latest export types.
If the export types have changed then the Vite dev server is restarted.

Note that restarting Miniflare without also restarting the dev server is problematic at this stage. This is because the dev server restart includes teardown and reinitialisation of environments that would otherwise have to be replicated somehow. Restarting the dev server is the best option in this phase and makes the behaviour of updating export types equivalent to updating the Worker config file.

Tests
- Tests included
- Tests not necessary because:
Public documentation
- Cloudflare docs PR(s):
- Documentation not necessary because: already documented
Wrangler V3 Backport
- Wrangler PR:
- Not necessary because: not a Wrangler change

changeset-bot · 2025-11-11T15:40:50Z

🦋 Changeset detected

Latest commit: 097065b

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

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-11-11T15:49:19Z

create-cloudflare

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

@cloudflare/kv-asset-handler

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

miniflare

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

@cloudflare/pages-shared

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

@cloudflare/unenv-preset

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

@cloudflare/vite-plugin

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

@cloudflare/vitest-pool-workers

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

@cloudflare/workers-editor-shared

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

@cloudflare/workers-utils

npm i https://pkg.pr.new/@cloudflare/workers-utils@11238

wrangler

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

commit: 097065b

packages/vite-plugin-cloudflare/package.json

github-actions · 2025-11-12T13:59:58Z

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 james/ctx-exports might be a good starting point.

Notes:

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

jamesopstad · 2025-11-13T09:54:00Z

packages/vite-plugin-cloudflare/src/plugins/virtual-modules.ts

+
+		let exportType
+
+		if (typeof value === "function") {


I think it would be good to warn the user if they have other export types in their entry module. That could be done in a follow-up PR.

…a single Map

… move warnings playground into e2e test. This is because the dev server will now error on startup.

ascorbic · 2025-11-13T12:51:50Z

Could you update the description to give some background for the change – why it's needed, how it's used etc?

jamesopstad · 2025-11-13T14:07:08Z

Could you update the description to give some background for the change – why it's needed, how it's used etc?

Updated.

edmundhung

I am still going through the second half of the commits. Just a few nits so far

edmundhung · 2025-11-13T12:01:22Z

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

-		workers[workerEnvironmentName] = workerConfig;
+		environmentNameToWorkerMap.set(
+			workerEnvironmentName,
+			setWorker(workerConfig)


Nit: It might just be me but the term "set" seems confusing. How about resolveWorker? We can also change setWorker to accept the environmentNameToWorkerMap and update the map within it.

edmundhung · 2025-11-13T14:26:40Z

packages/vite-plugin-cloudflare/src/export-types.ts

+				const exportTypes = await (
+					viteDevServer.environments[
+						environmentName
+					] as CloudflareDevEnvironment


Would it be worth introducing a helper like getCloudflareDevEnvironment that throws if the environment is not an instance of CloudflareDevEnvironment?

edmundhung · 2025-11-13T14:36:28Z

packages/vite-plugin-cloudflare/src/plugins/dev.ts

+					({ miniflareOptions, containerTagToOptionsMap } =
+						await getDevMiniflareOptions(ctx, viteDevServer));


Nit: It look me a while to realize we are updating the variables here instead of defining an inline function 😅

Should we make it more explicit?

const updatedOptions = await getDevMiniflareOptions(ctx, viteDevServer); miniflareOptions = updatedOptions.miniflareOptions; containerTagToOptionsMap = updatedOptions.containerTagToOptionsMap;

edmundhung · 2025-11-13T14:44:28Z

packages/vite-plugin-cloudflare/src/export-types.ts

+function getWorkerNameToWorkflowEntrypointExportsMap(
+	workers: Worker[]
+): Map<string, Set<string>> {


Nit: Would it be better to have this exported from wrangler or @cloudflare/workers-utils directly instead of a random getDurableObjectClassNameToUseSQLiteMap helper?

Happy to keep this as is for now.

edmundhung · 2025-11-13T14:56:16Z

packages/vite-plugin-cloudflare/src/export-types.ts

+			const exportTypes: ExportTypes = Object.fromEntries([
+				...[...workerEntrypointExports].map(
+					(exportName) => [exportName, "WorkerEntrypoint"] as const
+				),
+				...[...durableObjectExports].map(
+					(exportName) => [exportName, "DurableObject"] as const
+				),
+				...[...workflowEntrypointExports].map(
+					(exportName) => [exportName, "WorkflowEntrypoint"] as const
+				),
+			]);


Suggested change

const exportTypes: ExportTypes = Object.fromEntries([

...[...workerEntrypointExports].map(

(exportName) => [exportName, "WorkerEntrypoint"] as const

),

...[...durableObjectExports].map(

(exportName) => [exportName, "DurableObject"] as const

),

...[...workflowEntrypointExports].map(

(exportName) => [exportName, "WorkflowEntrypoint"] as const

),

]);

const exportTypes: ExportTypes = {};

for (const exportName of workerEntrypointExports) {

exportTypes[exportName] ??= "WorkerEntrypoint";

}

for (const exportName of durableObjectExports) {

exportTypes[exportName] ??= "DurableObject";

}

for (const exportName of workflowEntrypointExports) {

exportTypes[exportName] ??= "WorkflowEntrypoint";

}

edmundhung

Looks good. Just a few minor nits.

edmundhung · 2025-11-13T16:13:30Z

packages/vite-plugin-cloudflare/playground/ctx-exports/__tests__/ctx-exports.spec.ts

+		// Wait long enough to ensure that the server would have restarted if it was restarting
+		await new Promise((resolve) => setTimeout(resolve, 2000));


Instead of waiting for 2 second. How about updating the entry file to return a different text response without changing the exports?

workers-devprod added this to workers-sdk Nov 11, 2025

github-project-automation bot moved this to Untriaged in workers-sdk Nov 11, 2025

jamesopstad force-pushed the james/ctx-exports branch from 69919d4 to d4e9916 Compare November 11, 2025 15:47

jamesopstad force-pushed the james/ctx-exports branch 4 times, most recently from 59a54d3 to ec6fc66 Compare November 12, 2025 13:02

jamesopstad commented Nov 12, 2025

View reviewed changes

packages/vite-plugin-cloudflare/package.json Show resolved Hide resolved

jamesopstad marked this pull request as ready for review November 12, 2025 13:58

jamesopstad requested review from a team as code owners November 12, 2025 13:58

jamesopstad added the vite-plugin Relating to the `@cloudflare/vite-plugin` package label Nov 12, 2025

jamesopstad added the skip-v3-pr Skip validation of presence of a v3 backport PR label Nov 12, 2025

jamesopstad changed the title ~~Support ctx.exports~~ Support ctx.exports in the Vite plugin Nov 12, 2025

jamesopstad force-pushed the james/ctx-exports branch 3 times, most recently from 5af2908 to c44ccc4 Compare November 13, 2025 09:11

jamesopstad commented Nov 13, 2025

View reviewed changes

jamesopstad added 9 commits November 13, 2025 10:50

Add ctx-exports playground and failing tests

e025afc

Add virtual module to expose function for getting Worker export types

44b95ae

Refactor resolvedPluginConfig to combine workers and ndoeJsCompat in …

87c22cb

…a single Map

Restart Miniflare during dev server start when export types do not match

414e816

Rename getClassNamesWhichUseSQLite

20fc843

Export unstable_getDurableObjectClassNameToUseSQLiteMap from Wrangler

1e37fb2

Get export types from config and merge with those derived from code

0471d8f

Restart dev server when Worker exports change

c1474de

Render any captured nodejs_compat warnings when the process exits and…

000b1cc

… move warnings playground into e2e test. This is because the dev server will now error on startup.

jamesopstad added 3 commits November 13, 2025 10:51

Add tests for file changes

2953f51

Add changesets

c269fb2

Fix path matching in e2e test

097065b

jamesopstad force-pushed the james/ctx-exports branch from c44ccc4 to 097065b Compare November 13, 2025 10:53

edmundhung reviewed Nov 13, 2025

View reviewed changes

edmundhung approved these changes Nov 13, 2025

View reviewed changes

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

		({ miniflareOptions, containerTagToOptionsMap } =
		await getDevMiniflareOptions(ctx, viteDevServer));

		// Wait long enough to ensure that the server would have restarted if it was restarting
		await new Promise((resolve) => setTimeout(resolve, 2000));

Support ctx.exports in the Vite plugin #11238

Are you sure you want to change the base?

Support ctx.exports in the Vite plugin #11238

Conversation

jamesopstad commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Initial server start

Updates to Worker entry modules

Uh oh!

changeset-bot bot commented Nov 11, 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 Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Nov 12, 2025

Uh oh!

jamesopstad Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

ascorbic commented Nov 13, 2025

Uh oh!

jamesopstad commented Nov 13, 2025

Uh oh!

edmundhung left a comment

Choose a reason for hiding this comment

Uh oh!

edmundhung Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

edmundhung Nov 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!

edmundhung Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

edmundhung Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

edmundhung Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

edmundhung left a comment

Choose a reason for hiding this comment

Uh oh!

edmundhung Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Support `ctx.exports` in the Vite plugin #11238

Support `ctx.exports` in the Vite plugin #11238

jamesopstad commented Nov 11, 2025 •

edited

Loading

changeset-bot bot commented Nov 11, 2025 •

edited

Loading

pkg-pr-new bot commented Nov 11, 2025 •

edited

Loading

edmundhung Nov 13, 2025 •

edited

Loading