docs: explain how external modules work in rolldown#8415
Conversation
How to use the Graphite Merge QueueAdd 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. |
✅ Deploy Preview for rolldown-rs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation explaining how external modules work in Rolldown. The documentation provides an end-to-end guide covering how modules become external, how import paths are determined in the output, and how the relevant options and plugin hooks interact.
Changes:
- Added a new in-depth guide at
docs/in-depth/external-modules.mdwith 281 lines of comprehensive documentation - Added cross-references from the
externalandmakeAbsoluteExternalsRelativeoption docs to the new guide - Updated the VitePress sidebar configuration to include the new guide in the navigation
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| docs/in-depth/external-modules.md | New comprehensive guide explaining external module resolution, the two-check external option behavior, plugin control via resolveId, makeAbsoluteExternalsRelative option, and the full resolution flow with special cases |
| packages/rolldown/src/options/docs/external.md | Added cross-reference link to the new External Modules Guide for detailed explanation |
| packages/rolldown/src/options/docs/make-absolute-externals-relative.md | Added cross-reference link to the new External Modules Guide for detailed explanation |
| docs/.vitepress/config.ts | Added "External Modules" entry to the In-Depth sidebar navigation |
There was a problem hiding this comment.
I think this page should focus on what is done in what order, and how each option works should probably be left to each options' page.
There was a problem hiding this comment.
how each option works
From my experience, I failed to understand big picture of the external modules mechanism from the previous doc. This post is for this purpose. To understand how they all work together, you have put them together and talk about how they interact with each other.
There was a problem hiding this comment.
🥲 I can't get what https://rolldown.rs/reference/InputOptions.makeAbsoluteExternalsRelative is talking about at first. It's too scoped.
After this article, I start to understand the https://rolldown.rs/reference/InputOptions.makeAbsoluteExternalsRelative actually make sense, but that's the issue. It's not friendly to build mental model of how external modules work.
There was a problem hiding this comment.
I tried to re-organize the content here: #8457
Does this one make sense?
|
|
||
| ### Data URLs and HTTP URLs | ||
|
|
||
| Specifiers starting with `data:`, `http://`, `https://`, or `//` are **automatically treated as external** before the internal resolver runs, regardless of the `external` option. These IDs are not affected by `makeAbsoluteExternalsRelative`. |
There was a problem hiding this comment.
Isn't data: handled by the internal plugin and bundled?
There was a problem hiding this comment.
rolldown/crates/rolldown_plugin_data_uri/src/lib.rs
Lines 50 to 53 in 169a3f9
dataurl plugin only handle valid/scoped dataurl.
No description provided.