Skip to content

feat: import.meta.ROLLDOWN_FILE_URL_<referenceId>_<urlId> support to pass context to resolveFileUrl hook#10297

Merged
graphite-app[bot] merged 1 commit into
mainfrom
07-15-feat_import.meta.rolldown_file_url__referenceid___urlid_support_to_pass_context_to_resolvefileurl_hook
Jul 22, 2026
Merged

feat: import.meta.ROLLDOWN_FILE_URL_<referenceId>_<urlId> support to pass context to resolveFileUrl hook#10297
graphite-app[bot] merged 1 commit into
mainfrom
07-15-feat_import.meta.rolldown_file_url__referenceid___urlid_support_to_pass_context_to_resolvefileurl_hook

Conversation

@sapphi-red

@sapphi-red sapphi-red commented Jul 15, 2026

Copy link
Copy Markdown
Member

This PR adds a new feature to import.meta.ROLLDOWN_FILE_URL_<referenceId>.

Currently, these file URL references does not have a way to differentiate each references when resolveFileUrl hook is called. But that is sometimes needed. For example, in Vite, there are three cases:

  • The wasm plugin emits the reference to the wasm binary. In SSR, this reference to the wasm binary should be rendered in a way that accesses as a relative path (as it's a file read). But in other plugins, the wasm binary should be rendered as the URL that can be accessed from the browser (this may sound strange, but it's the current behavior). So the import.meta.ROLLDOWN_FILE_URL_<referenceId> needs to be differentiated with type it is.
  • Vite has ?inline query which forces the asset to be output as data URL. The same asset can be imported with the query in some places while it can also be imported without the query in other places. This means the same asset needs to be referenced differently depending on the reference.
  • Vite never inlines assets specified as the entrypoint. This information is tied to a single reference.

rendered docs

In this PR, I made the urlId generated on the plugin side, but maybe that should be generated on the Rolldown side so that a conflict never happens. This can be done by adding this.generateFileUrlId.

The API can also be expanded to store the metadata in the Rolldown side. Currently, The metadata lives on the plugin side, so the referenceId emit and the resolveFileUrl hook needs to be coupled. This works for Vite's case, but won't work in general. For now, I think it's ok to go without it.

refs vitejs/vite#22962

sapphi-red commented Jul 15, 2026

Copy link
Copy Markdown
Member Author

How to use the Graphite Merge Queue

Add the label graphite: merge-when-ready to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

@sapphi-red
sapphi-red force-pushed the 07-15-feat_support_import.meta.rolldown_file_url__ branch from 42cb429 to d443874 Compare July 16, 2026 11:29
@sapphi-red
sapphi-red force-pushed the 07-15-feat_import.meta.rolldown_file_url__referenceid___urlid_support_to_pass_context_to_resolvefileurl_hook branch 2 times, most recently from c927fea to 45b086b Compare July 16, 2026 11:50
@sapphi-red
sapphi-red changed the base branch from 07-15-feat_support_import.meta.rolldown_file_url__ to graphite-base/10297 July 17, 2026 03:48
@sapphi-red
sapphi-red force-pushed the graphite-base/10297 branch from d443874 to ce98ae7 Compare July 17, 2026 06:30
@sapphi-red
sapphi-red force-pushed the 07-15-feat_import.meta.rolldown_file_url__referenceid___urlid_support_to_pass_context_to_resolvefileurl_hook branch from 45b086b to e94d186 Compare July 17, 2026 06:30
@sapphi-red
sapphi-red changed the base branch from graphite-base/10297 to main July 17, 2026 06:30
@sapphi-red sapphi-red self-assigned this Jul 17, 2026
@sapphi-red
sapphi-red marked this pull request as ready for review July 17, 2026 07:53
@codspeed-hq

codspeed-hq Bot commented Jul 17, 2026

Copy link
Copy Markdown

Merging this PR will not alter performance

✅ 7 untouched benchmarks
⏩ 10 skipped benchmarks1


Comparing 07-15-feat_import.meta.rolldown_file_url__referenceid___urlid_support_to_pass_context_to_resolvefileurl_hook (598cbea) with main (9b0ad5b)

Open in CodSpeed

Footnotes

  1. 10 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports.

@hyfdev hyfdev left a comment

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.

The fixed-length split is sound: reference ids are always exactly 22 chars of base64url from assign_reference_id, and the new lockstep test in file_emitter.rs guards that invariant. Per-occurrence results keyed by (ModuleIdx, NodeId) mean the same file referenced with different urlIds resolves independently, and the ROLLUP_FILE_URL_ alias keeps Rollup semantics by never parsing a suffix.

Generating the urlId on the plugin side (rather than a Rolldown-side generateFileUrlId) covers the use cases described: the plugin controls both the reference spelling and the hook, so urlId conflicts stay within one plugin's namespace.

Left a few small notes on the docs and test coverage; nothing blocking.

Comment thread docs/apis/plugin-api/file-urls.md Outdated
Comment thread crates/rolldown/src/utils/file_url.rs Outdated
@sapphi-red
sapphi-red force-pushed the 07-15-feat_import.meta.rolldown_file_url__referenceid___urlid_support_to_pass_context_to_resolvefileurl_hook branch from e94d186 to cacdf16 Compare July 17, 2026 13:18
@netlify

netlify Bot commented Jul 17, 2026

Copy link
Copy Markdown

Deploy Preview for rolldown-rs canceled.

Name Link
🔨 Latest commit 0d45611
🔍 Latest deploy log https://app.netlify.com/projects/rolldown-rs/deploys/6a609f187274c600090c31a1

@sapphi-red
sapphi-red force-pushed the 07-15-feat_import.meta.rolldown_file_url__referenceid___urlid_support_to_pass_context_to_resolvefileurl_hook branch 2 times, most recently from 598cbea to 68065e5 Compare July 22, 2026 10:38
@sapphi-red

Copy link
Copy Markdown
Member Author

marked as experimental (may change in minors)

sapphi-red commented Jul 22, 2026

Copy link
Copy Markdown
Member Author

Merge activity

  • Jul 22, 10:39 AM UTC: The merge label 'graphite: merge-when-ready' was detected. This PR will be added to the Graphite merge queue once it meets the requirements.
  • Jul 22, 10:43 AM UTC: sapphi-red added this pull request to the Graphite merge queue.
  • Jul 22, 10:49 AM UTC: Merged by the Graphite merge queue.

…o pass context to `resolveFileUrl` hook (#10297)

This PR adds a new feature to `import.meta.ROLLDOWN_FILE_URL_<referenceId>`.

Currently, these file URL references does not have a way to differentiate each references when `resolveFileUrl` hook is called. But that is sometimes needed. For example, in Vite, there are three cases:

- The wasm plugin emits the reference to the wasm binary. In SSR, this reference to the wasm binary should be rendered in a way that accesses as a relative path (as it's a file read). But in other plugins, the wasm binary should be rendered as the URL that can be accessed from the browser (this may sound strange, but it's the current behavior). So the `import.meta.ROLLDOWN_FILE_URL_<referenceId>` needs to be differentiated with type it is.
- Vite has `?inline` query which forces the asset to be output as `data` URL. The same asset can be imported with the query in some places while it can also be imported without the query in other places. This means the same asset needs to be referenced differently depending on the reference.
- Vite never inlines assets specified as the entrypoint. This information is tied to a single reference.

[rendered docs](https://github.com/rolldown/rolldown/blob/07-15-feat_import.meta.rolldown_file_url__referenceid___urlid_support_to_pass_context_to_resolvefileurl_hook/docs/apis/plugin-api/file-urls.md#passing-a-urlid)

In this PR, I made the `urlId` generated on the plugin side, but maybe that should be generated on the Rolldown side so that a conflict never happens. This can be done by adding `this.generateFileUrlId`.

The API can also be expanded to store the metadata in the Rolldown side. Currently, The metadata lives on the plugin side, so the referenceId emit and the `resolveFileUrl` hook needs to be coupled. This works for Vite's case, but won't work in general. For now, I think it's ok to go without it.

refs vitejs/vite#22962
@graphite-app
graphite-app Bot force-pushed the 07-15-feat_import.meta.rolldown_file_url__referenceid___urlid_support_to_pass_context_to_resolvefileurl_hook branch from 68065e5 to 0d45611 Compare July 22, 2026 10:44
@graphite-app
graphite-app Bot merged commit 0d45611 into main Jul 22, 2026
34 checks passed
@graphite-app
graphite-app Bot deleted the 07-15-feat_import.meta.rolldown_file_url__referenceid___urlid_support_to_pass_context_to_resolvefileurl_hook branch July 22, 2026 10:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants