docs: rework options documentation first round #6542
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Member
Author
How to use the Graphite Merge QueueAdd the label graphite: merge 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. |
68f6a6c to
3d8b9c4
Compare
2f2430b to
44bf8ba
Compare
Contributor
There was a problem hiding this comment.
Pull Request Overview
Reworks and restructures the configuration documentation into standalone option pages, updates navigation/redirects, and introduces a glossary for clearer terminology.
- New distributed pages for individual options with examples and in-depth notes
- Updated site navigation, sidebars, and redirects to the new structure
- Added glossary entries and fixed/updated cross-links in guides
Reviewed Changes
Copilot reviewed 31 out of 31 changed files in this pull request and generated 11 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/options/tsconfig.md | New tsconfig option docs with examples and precedence notes |
| docs/options/treeshake.md | New treeshake option page |
| docs/options/shim-missing-exports.md | New shimMissingExports option page with scenario example |
| docs/options/resolve.md | New resolve options page (alias, conditions, fields, extensions, etc.) |
| docs/options/preserve-entry-signatures.md | New preserveEntrySignatures option page |
| docs/options/platform.md | New platform option page with presets and differences from esbuild |
| docs/options/output.md | Comprehensive output options reference |
| docs/options/output-sourcemap.md | Detailed sourcemap options and behaviors |
| docs/options/output-generated-code.md | Generated code options page |
| docs/options/output-advanced-chunks.md | Advanced chunking configuration and examples |
| docs/options/optimization.md | Optimization options (inlineConst) |
| docs/options/onwarn.md | onwarn API (deprecated) with pointer to onLog |
| docs/options/on-log.md | onLog API page |
| docs/options/module-types.md | moduleTypes option overview |
| docs/options/log-level.md | logLevel option |
| docs/options/input.md | input option with examples and glossary cross-links |
| docs/options/external.md | external option with performance notes and patterns |
| docs/options/experimental.md | Experimental options and guidance |
| docs/options/cwd.md | cwd option |
| docs/options/context.md | context option with examples |
| docs/in-depth/advanced-chunks.md | Updated links to new options pages |
| docs/guide/troubleshooting.md | Updated plugin equivalence references to new paths |
| docs/guide/notable-features.md | Updated references to options pages |
| docs/glossary/user-defined-entry.md | New glossary entry |
| docs/glossary/index.md | New glossary index |
| docs/glossary/entry.md | New glossary entry |
| docs/glossary/entry-name.md | New glossary entry |
| docs/glossary/entry-chunk.md | New glossary entry with example outputs |
| docs/apis/config-options.md | Removed obsolete page in favor of new structure |
| docs/.vitepress/theme/LayoutWithRedirect.vue | Added redirect from old config options path to new options index |
| docs/.vitepress/config.ts | Added options and glossary sidebars; updated nav to new config landing |
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
2dc25fe to
d23c703
Compare
d23c703 to
58fd648
Compare
TheAlexLichter
approved these changes
Oct 20, 2025
Collaborator
TheAlexLichter
left a comment
There was a problem hiding this comment.
Great first iteration! No major issues but some comments for improvement from a users perspective
| @@ -0,0 +1,73 @@ | |||
| # Entry Chunk | |||
|
|
|||
| An entry chunk is created, because we need to output a JavaScript file for: | |||
Collaborator
There was a problem hiding this comment.
Should we explain what an entry chunk is first?
Member
Author
There was a problem hiding this comment.
It should be included in the Chunk term.
| @@ -0,0 +1,3 @@ | |||
| # Entry Name | |||
|
|
|||
| Entry name is a property of an entry. Rolldown will use the entry name to generate the file name for the corresponding entry chunk, which will replace the `[name]` placeholder in the [`output.entryFileNames`](../options/output#entryfilenames) pattern. | |||
Collaborator
There was a problem hiding this comment.
Should we link to the entry chunk config here?
Member
Author
There was a problem hiding this comment.
Yes. It's an unfinished puzzle a lot of to done. Could wait for a time we could batch the changes.
| # Glossary | ||
|
|
||
| Common terms and concepts used in Rolldown documentation. | ||
|
|
Collaborator
There was a problem hiding this comment.
Ideas to add:
- Module
- Facade Module
- Alias (vs entry)
Member
Author
There was a problem hiding this comment.
Yes. Glossary will be improved during polishing. Improving it only need to wait for a while, it's too much of work.
|
|
||
| Rolldown supports the following transforms out of the box, powered by [Oxc](https://oxc.rs/docs/guide/usage/transformer). | ||
| The transform is configurable via the [`transform`](/apis/config-options#transform) option. | ||
| The transform is configurable via the `transform` option. |
Collaborator
There was a problem hiding this comment.
Is there no new link here?
Member
Author
There was a problem hiding this comment.
No. transform page is missing currently.
|
|
||
| ## Examples | ||
|
|
||
| ### Basic vendor chunk |
Collaborator
There was a problem hiding this comment.
Can we add a short explanation for each example?
| - **Default:** `0` | ||
| - **Path:** `output.advancedChunks.groups[].minSize` | ||
|
|
||
| Minimum size in bytes of the desired chunk. If the accumulated size is smaller, the group is ignored. |
Collaborator
There was a problem hiding this comment.
What does it mean if the group is ignored?
| "jsx": "react-jsx", | ||
| "baseUrl": ".", | ||
| "paths": { | ||
| "@/*": ["src/*"], |
Collaborator
There was a problem hiding this comment.
Aide note: paths should be used as "source of truth" according to the ts team
| Notable differences from esbuild's `platform` option: | ||
|
|
||
| - The default output format is always `'esm'` regardless of platform (in esbuild, Node.js defaults to `'cjs'`) | ||
| - No automatic `</script>` escape behavior when platform is `'browser'` |
Collaborator
There was a problem hiding this comment.
Can we get more info about this?
| - **Type:** `false | 'strict' | 'allow-extension' | 'exports-only'` | ||
| - **Default:** `'exports-only'` | ||
|
|
||
| Controls how entry chunk exports are preserved and whether entry modules can be combined with other modules. |
Collaborator
There was a problem hiding this comment.
Here examples would be great!
8962d37 to
dd08c4b
Compare
Member
Author
|
@TheAlexLichter Thank you for the all delicate reviews! It takes too much of time to solve them for merging this PR. I'm gonna merge this PR with keeping theose comments open, so they could be references for future polishing. I'd recorded them here #6089 (comment). |
shulaoda
added a commit
that referenced
this pull request
Oct 27, 2025
## [1.0.0-beta.45] - 2025-10-27 ### 🚀 Features - plugin/vite-resolve: add `legacyInconsistentCjsInterop` option (#6687) by @sapphi-red - rolldown_plugin_vite_css_post: initialize `CSSStyles` (#6691) by @shulaoda - rolldown_plugin_manifest: align with `vitejs/vite#20585` (#6684) by @shulaoda - enabling mangle private class members (#6679) by @IWANABETHATGUY - rolldown_resolver: auto tsconfig discovery (#6602) by @Boshen - support named imports + CJS by optimization.inlineConst (#6644) by @IWANABETHATGUY ### 🐛 Bug Fixes - rolldown_binding: use Record instead of Map (#6715) by @shulaoda - validate valibot schema against existing type (#6703) by @ocavue - rolldown_plugin_vite_css_post: align some logic (#6697) by @shulaoda - node/options: should validate `transform.jsx` correctly (#6698) by @ocavue - inherit runtime helpers from eliminated dependencies (#6689) by @IWANABETHATGUY - clean-dir: advance clean outdir to allow `generateBundle` outputs (#6647) by @aprosail - rename variable to better reflect its purpose and fix CJS imports (#6663) by @IWANABETHATGUY - bailout tree shake commonjs export when it is defined multiple time (#6659) by @IWANABETHATGUY - rolldown_plugin_reporter: color dimmed text correctly (#6649) by @sapphi-red - don't inline json module when used as a namespace reference (#6652) by @IWANABETHATGUY - avoid `define` deprecation warning when loading a config file (#6641) by @sapphi-red ### 💼 Other - pluginutils: switch to tsc to solve the issue of loading conflicting binary (#6708) by @hyf0 ### 🚜 Refactor - node: only call `transformToRollupOutput` when needed (#6695) by @hyf0 - node: split `transformToRollupOutput` into mutable and immutable versions (#6693) by @hyf0 - remove unnecessaey lazy data passing for `BindingOutputs` (#6692) by @hyf0 - rolldown_plugin_utils: tweak `CSSEntriesCache` (#6685) by @shulaoda - rolldown_binding: use unified `BindingRenderBuiltUrl` (#6653) by @shulaoda ### 📚 Documentation - in-depth about `experimental.nativeMagicString` (#6713) by @IWANABETHATGUY - polish `optimization` (#6719) by @IWANABETHATGUY - clarify `output.cleanDir` timing behavior for plugin compatibility (#6682) by @Copilot - add Kevin Deng, 翠 (sapphi-red), and Alexander Lichter to team page with Bluesky links (#6664) by @Copilot - polish `preserveEntrySignature` doc (#6661) by @IWANABETHATGUY - set up redirects via netlify (#6654) by @TheAlexLichter - polish doc about `treeshake` (#6650) by @IWANABETHATGUY - rework options documentation first round (#6542) by @hyf0 ### ⚡ Performance - rolldown: upgrade sugar_path (#6646) by @Brooooooklyn ### 🧪 Testing - add live bindings test for default export snapshot semantics (#6538) by @Copilot ### ⚙️ Miscellaneous Tasks - deps: lock file maintenance npm packages (#6714) by @renovate[bot] - deps: update github-actions (#6710) by @renovate[bot] - deps: update dependency @vueuse/core to v14 (#6711) by @renovate[bot] - deps: update github-actions (major) (#6712) by @renovate[bot] - deps: update dependency tsdown to v0.15.10 (#6706) by @renovate[bot] - remove `typedoc` dependency and cleanup unused documentation generation (#6686) by @Copilot - deps: update dependency rolldown-plugin-dts to v0.17.1 (#6690) by @renovate[bot] - lint: `oxlint --type-aware` (#5660) by @Boshen - rolldown: update napi and js binding (#6676) by @Brooooooklyn - deps: update vitest to v4 (#6673) by @sapphi-red - test: support `DevTestMeta#dev` (#6672) by @hyf0 - deps: update dependency rolldown-plugin-dts to ^0.17.0 (#6671) by @renovate[bot] - test: move dev related options to rolldown_dev_common (#6667) by @hyf0 - test: add `DevTestMeta` under `TestMeta#dev` to control dev related behaviors (#6666) by @hyf0 - deps: update dependency vite to v7.1.11 [security] (#6645) by @renovate[bot] - pluginutils: use rolldown to build plugutils (#6642) by @Brooooooklyn - deps: update dependency tsdown to v0.15.9 (#6643) by @renovate[bot] ### ❤️ New Contributors * @ocavue made their first contribution in [#6703](#6703) Co-authored-by: shulaoda <165626830+shulaoda@users.noreply.github.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Preview: https://deploy-preview-6542--rolldown-rs.netlify.app/options/input
The new documentation featured:
Todos
It's too much to gather all changes into one PR. Though I finished the basics first, which is much better than the previous one.
Here are todos I record at #6089 (comment), which will be solved in the subsquent PRs.
Missing page:
To be polished in the second rounds
To be improved (as a reminder)
resolve options's in-depth, should warn about overwriten optionsextensionAlias, should warn about adding.jsand the trap of resolving.jsitself.extensionAlias, the doc mentioned it could be used to handle ts. Should invetigate about whether we already handle the situation.