docs: explain how external modules work in rolldown by sapphi-red · Pull Request #8457 · rolldown/rolldown

sapphi-red · 2026-02-25T04:29:38Z

Co-authored-by: Yunfei He [email protected]

sapphi-red · 2026-02-25T04:29:52Z

docs: explain how external modules work in rolldown #8457 👈 (View in Graphite)
main

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.

netlify · 2026-02-25T04:30:46Z

✅ Deploy Preview for rolldown-rs ready!

Name	Link
🔨 Latest commit	`8a28ad6`
🔍 Latest deploy log	https://app.netlify.com/projects/rolldown-rs/deploys/69a41f8f3553e5000840b766
😎 Deploy Preview	https://deploy-preview-8457--rolldown-rs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Copilot

Pull request overview

Adds/updates documentation to explain Rolldown’s external module behavior end-to-end, including how external matching works and how output paths are determined.

Changes:

Expanded docs for makeAbsoluteExternalsRelative with value-specific behavior, examples, and caveats.
Clarified external option behavior (two-phase matching) and linked to a new in-depth guide.
Added a new “External Modules” in-depth page and surfaced it in the VitePress sidebar.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

File	Description
packages/rolldown/src/options/docs/make-absolute-externals-relative.md	Reworks reference text with clearer value semantics, examples, and a warning about dedup behavior.
packages/rolldown/src/options/docs/external.md	Documents two-stage `external` matching and links to the new in-depth guide; updates `/node_modules/` caveat wording.
docs/in-depth/external-modules.md	New in-depth guide describing externalization paths, resolution flow, and special cases.
docs/.vitepress/config.ts	Adds the new in-depth page to the sidebar.

packages/rolldown/src/options/docs/make-absolute-externals-relative.md

docs/in-depth/external-modules.md

packages/rolldown/src/options/docs/external.md

packages/rolldown/src/options/docs/make-absolute-externals-relative.md

hyf0

Couldn't be better than #8415!

sapphi-red · 2026-02-27T13:18:48Z

I've changed the content further.

packages/rolldown/src/options/docs/make-absolute-externals-relative.md

hyf0 · 2026-03-01T11:05:20Z

Merge activity

Mar 1, 11:05 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.
Mar 1, 11:05 AM UTC: hyf0 added this pull request to the Graphite merge queue.
Mar 1, 11:24 AM UTC: Merged by the Graphite merge queue.

close #8415 Co-authored-by: Yunfei He <[email protected]>

@IWANABETHATGUY

## [1.0.0-rc.7] - 2026-03-05 ⚡ Smarter Code Generation Defaults - DCE-only minification and smart constant inlining are now enabled by default - Produces cleaner, smaller output bundles without requiring explicit configuration 💡 LLM-Friendly Bundle Analyzer Reports - New markdown output format for the bundle analyzer plugin with bundle summaries, module graphs, dependency chains, and optimization suggestions - Optimization suggestions now also recommend using the entriesAware option when common chunks contain modules only reachable from specific entries ### 💥 BREAKING CHANGES - enable minify: 'dce-only' by default (#8465) by @IWANABETHATGUY - settings `inlineConst: { mode: 'smart', pass: 1}` by default (#8444) by @IWANABETHATGUY ### 🚀 Features - binding: add original getter to BindingMagicString (#8533) by @IWANABETHATGUY - native-magic-string: add `offset` property support (#8531) by @IWANABETHATGUY - add `output.strict` option to control `"use strict"` directive emission (#8489) by @Copilot - watch: expose `watcher.compareContentsForPolling` (#8526) by @hyf0 - watch: use new watcher to support watch mode (#8475) by @hyf0 - rust/watch: handle bulk-change (#8466) by @hyf0 - add LLM-friendly markdown output format to bundle analyzer plugin (#8242) by @IWANABETHATGUY ### 🐛 Bug Fixes - expose `plugins` on `NormalizedInputOptions` for `buildStart` hook (#8521) by @Copilot - only uppercase facade symbols in JSX preserve mode (#8519) by @IWANABETHATGUY - binding: export BindingResult in generated dts header (#8537) by @minsoo-web - pre-resolve paths option to avoid `invoke_sync` deadlock (#8518) by @IWANABETHATGUY - remove debug-only jsx_preset and UntranspiledSyntaxError (#8511) by @IWANABETHATGUY - apply `topLevelVar` to exported `const`/`let` declarations (#8507) by @IWANABETHATGUY - rolldown_plugin_vite_web_worker_post: avoid replacing `new.target` (#8488) by @sapphi-red - update copyright year to 2026 (#8486) by @maciekzygmunt ### 🚜 Refactor - rust: use Oxc's SymbolFlags::ConstVariable instead of custom IsConst flag (#8543) by @Dunqing - rust: remove FacadeScoping, use Scoping::create_symbol for facade symbols (#8540) by @Dunqing - rust/watch: remove hacky `reset_closed_for_watch_mode` (#8530) by @hyf0 - binding: return &str instead of String in filename() getter (#8534) by @IWANABETHATGUY - rust: remove old watch mode implementation (#8525) by @hyf0 - rust/watch: simply watch logic in the binding layer (#8516) by @hyf0 - rust/watch: tweak struct/function names (#8464) by @hyf0 ### 📚 Documentation - explain how external modules work in rolldown (#8457) by @sapphi-red - add some diagrams using graphviz (#8499) by @sapphi-red - use `vitepress-plugin-graphviz` (#8498) by @sapphi-red - list s390x/ppc64le prebuilt binaries (#8495) by @crusty-voidzero - fix error type for `RolldownBuild.generate` and others (#8490) by @sapphi-red ### ⚡ Performance - string_wizard: reduce allocations and add ASCII fast paths (#8541) by @IWANABETHATGUY - use IndexBitSet to replace IndexVec<XXXIdx, bool> for module/stmt inclusion tracking (#8503) by @IWANABETHATGUY - plugin: use IndexBitSet to optimize skipped plugins checking (#8497) by @ShroXd - rust/tla: skip compute_tla if there is no module use TLA (#8487) by @ShroXd ### 🧪 Testing - node/watch: make watch tests run in concurrent and retry-able (#8512) by @hyf0 - add test case for static flag tree-shaking (#8476) by @IWANABETHATGUY - migrate post-banner sourcemap-with-shebang to Rust (#8477) by @Copilot ### ⚙️ Miscellaneous Tasks - vscode: `formatOnSave` for markdown files using oxc formatter (#8536) by @minsoo-web - deps: update test262 submodule for tests (#8528) by @sapphi-red - remove `retry` workaround from output paths test fixtures (#8520) by @Copilot - docs: add Shuyuan Wang (h-a-n-a) and remove from acknowledgements (#8509) by @Copilot - consolidate top_level_var test cases using configVariants (#8508) by @IWANABETHATGUY - add s390x and ppc64le linux gnu targets (#8493) by @Brooooooklyn ### ◀️ Revert - fix(rolldown): increase tokio blocking threads size for watch mode (#8517) by @hyf0 ### ❤️ New Contributors * @minsoo-web made their first contribution in [#8536](#8536) * @crusty-voidzero made their first contribution in [#8495](#8495) * @maciekzygmunt made their first contribution in [#8486](#8486) Co-authored-by: shulaoda <[email protected]>

github-actions bot assigned sapphi-red Feb 25, 2026

sapphi-red mentioned this pull request Feb 25, 2026

docs: explain how external modules work in rolldown #8415

Closed

sapphi-red marked this pull request as ready for review February 25, 2026 05:22

Copilot AI review requested due to automatic review settings February 25, 2026 05:22

Copilot started reviewing on behalf of sapphi-red February 25, 2026 05:23 View session

Copilot AI reviewed Feb 25, 2026

View reviewed changes

hyf0 approved these changes Feb 25, 2026

View reviewed changes

sapphi-red force-pushed the 02-25-docs_explain_how_external_modules_work_in_rolldown branch from 01d6513 to c2d312b Compare February 27, 2026 13:17

sapphi-red requested a review from hyf0 February 27, 2026 13:17

sapphi-red commented Feb 27, 2026

View reviewed changes

packages/rolldown/src/options/docs/make-absolute-externals-relative.md Show resolved Hide resolved

hyf0 approved these changes Mar 1, 2026

View reviewed changes

hyf0 added the graphite: merge-when-ready label Mar 1, 2026

docs: explain how external modules work in rolldown (#8457)

8a28ad6

close #8415 Co-authored-by: Yunfei He <[email protected]>

Copilot AI review requested due to automatic review settings March 1, 2026 11:14

sapphi-red review requested due to automatic review settings March 1, 2026 11:14

graphite-app bot force-pushed the 02-25-docs_explain_how_external_modules_work_in_rolldown branch from c2d312b to 8a28ad6 Compare March 1, 2026 11:14

graphite-app bot merged commit 8a28ad6 into main Mar 1, 2026
32 checks passed

graphite-app bot deleted the 02-25-docs_explain_how_external_modules_work_in_rolldown branch March 1, 2026 11:24

graphite-app bot removed the graphite: merge-when-ready label Mar 1, 2026

This was referenced Mar 4, 2026

release: v1.0.0-rc.7 #8539

Closed

release: v1.0.0-rc.7 #8547

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: explain how external modules work in rolldown#8457

docs: explain how external modules work in rolldown#8457
graphite-app[bot] merged 1 commit intomainfrom
02-25-docs_explain_how_external_modules_work_in_rolldown

sapphi-red commented Feb 25, 2026 •

edited

Loading

Uh oh!

sapphi-red commented Feb 25, 2026

Uh oh!

netlify bot commented Feb 25, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hyf0 left a comment

Uh oh!

sapphi-red commented Feb 27, 2026

Uh oh!

Uh oh!

hyf0 commented Mar 1, 2026 •

edited by graphite-app bot

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

sapphi-red commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sapphi-red commented Feb 25, 2026

How to use the Graphite Merge Queue

Uh oh!

netlify bot commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for rolldown-rs ready!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hyf0 left a comment

Choose a reason for hiding this comment

Uh oh!

sapphi-red commented Feb 27, 2026

Uh oh!

Uh oh!

hyf0 commented Mar 1, 2026 • edited by graphite-app bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge activity

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sapphi-red commented Feb 25, 2026 •

edited

Loading

netlify bot commented Feb 25, 2026 •

edited

Loading

hyf0 commented Mar 1, 2026 •

edited by graphite-app bot

Loading