Skip to content

Support packages and virtual modules in the main field of the Worker config#10212

Merged
jamesopstad merged 8 commits intomainfrom
james/resolve-main-in-plugin
Sep 10, 2025
Merged

Support packages and virtual modules in the main field of the Worker config#10212
jamesopstad merged 8 commits intomainfrom
james/resolve-main-in-plugin

Conversation

@jamesopstad
Copy link
Copy Markdown
Contributor

@jamesopstad jamesopstad commented Aug 4, 2025

Fixes #000.

Adds support for package exports and virtual modules in the main field of the Worker config. The primary use case is to enable users to directly provide a file exported by a framework as the Worker entry module.

The changes made as part of this PR also prepare for better Rolldown support. By using virtual modules as entry files, it will be easier to adopt Rolldown's hook filter feature. Avoiding calling this.resolve in load or transform hooks also prevents errors when using modules that may pass through @rollup/common-js, such as package exports.

The entry file name in the build output is now hardcoded to index.js. This was necessary because of using a virtual module but is also more reliable than inferring from the first entry chunk as users/frameworks may add additional entry chunks.


  • Tests
    • Tests included
    • Tests not necessary because:
  • Public documentation
    • Cloudflare docs PR(s): TODO
    • Documentation not necessary because: to be included in relevant framework guides
  • Wrangler V3 Backport
    • Wrangler PR:
    • Not necessary because: only adds a new experimental feature to Wrangler

@changeset-bot
Copy link
Copy Markdown

changeset-bot bot commented Aug 4, 2025

🦋 Changeset detected

Latest commit: 8a0fc4b

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 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
Copy link
Copy Markdown

pkg-pr-new bot commented Aug 4, 2025

create-cloudflare

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

@cloudflare/kv-asset-handler

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

miniflare

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

@cloudflare/pages-shared

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

@cloudflare/unenv-preset

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

@cloudflare/vite-plugin

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

@cloudflare/vitest-pool-workers

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

@cloudflare/workers-editor-shared

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

wrangler

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

commit: 8a0fc4b

@jamesopstad jamesopstad force-pushed the james/resolve-main-in-plugin branch 3 times, most recently from 1431592 to b7992c1 Compare August 4, 2025 14:31
@jamesopstad jamesopstad force-pushed the james/resolve-main-in-plugin branch 2 times, most recently from c241913 to e7dde15 Compare August 14, 2025 10:08
@jamesopstad jamesopstad force-pushed the james/resolve-main-in-plugin branch 5 times, most recently from 6fb4782 to aa165db Compare September 9, 2025 09:36
@jamesopstad jamesopstad changed the title Support virtual modules and package exports in the main field of the Worker config Support package exports and virtual modules in the main field of the Worker config Sep 9, 2025
@jamesopstad jamesopstad marked this pull request as ready for review September 9, 2025 10:35
@jamesopstad jamesopstad requested a review from a team as a code owner September 9, 2025 10:35
@jamesopstad jamesopstad requested a review from a team September 9, 2025 10:35
Comment on lines +352 to +354
if (!ENTRY_MODULE_EXTENSIONS.some((extension) => main.endsWith(extension))) {
return main;
}
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can technically include an extension in a package entrypoint, though that seems pretty uncommon. Would it be safer to default to treating it as a path, and only consider it a module if it does not exist on the file system?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The issue then is that it would be a change to the existing behaviour where we error if the file does not exist. There's also a slight risk that the file at the absolute path doesn't exist so we pass it through but then it resolves to a different (and unintended) file that does exist. Part of the problem is that we resolve the main field relative to the Worker config file and we treat paths as relative, even if they don't have leading ./.

Not allowing package.json exports that include a file extension seems like an OK tradeoff but open to other ideas here.

@jamesopstad jamesopstad force-pushed the james/resolve-main-in-plugin branch from aa165db to be0d1c4 Compare September 10, 2025 11:14
@github-actions
Copy link
Copy Markdown
Contributor

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/resolve-main-in-plugin might be a good starting point.

Notes:

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

@jamesopstad jamesopstad added skip-v3-pr vite-plugin Relating to the `@cloudflare/vite-plugin` package labels Sep 10, 2025
@jamesopstad jamesopstad force-pushed the james/resolve-main-in-plugin branch from be0d1c4 to 5aef76a Compare September 10, 2025 12:20
@jamesopstad jamesopstad changed the title Support package exports and virtual modules in the main field of the Worker config Support packages and virtual modules in the main field of the Worker config Sep 10, 2025
Copy link
Copy Markdown
Member

@edmundhung edmundhung left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔥

@github-project-automation github-project-automation bot moved this from Untriaged to Approved in workers-sdk Sep 10, 2025
@jamesopstad jamesopstad force-pushed the james/resolve-main-in-plugin branch from 5aef76a to 8afe079 Compare September 10, 2025 17:11
@jamesopstad jamesopstad force-pushed the james/resolve-main-in-plugin branch from 8afe079 to 8a0fc4b Compare September 10, 2025 20:12
@jamesopstad jamesopstad merged commit 0837a8d into main Sep 10, 2025
53 of 58 checks passed
@jamesopstad jamesopstad deleted the james/resolve-main-in-plugin branch September 10, 2025 21:25
@github-project-automation github-project-automation bot moved this from Approved to Done in workers-sdk Sep 10, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

vite-plugin Relating to the `@cloudflare/vite-plugin` package

Projects

Archived in project

Development

Successfully merging this pull request may close these issues.

3 participants