docs: clarify output.cleanDir timing behavior for plugin compatibility
#6682
+9
−1
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
Contributor
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. |
✅ Deploy Preview for rolldown-rs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Copilot
AI
changed the title
[WIP] Update documentation for new added behavior in options
docs: clarify Oct 24, 2025
output.cleanDir timing behavior for plugin compatibility
Member
Merge activity
|
shulaoda
approved these changes
Oct 24, 2025
…ity (#6682) ## Summary Updates the `output.cleanDir` documentation to clarify when directory cleanup occurs and how it affects plugin-generated files. ## Context PR #6486 introduced the `output.cleanDir` option to clean the output directory before emitting output. However, PR #6647 fixed an important timing issue where the cleanup was initially happening between `generateBundle` and `writeBundle` hooks, causing files created by plugins (like `@rollup/plugin-url` and `rollup-plugin-copy`) to be deleted. The fix moved the cleanup to occur **before** the `generateBundle` hook, ensuring all plugin-generated files are preserved. This documentation update clarifies this critical behavior for users. ## Changes ### Updated main description Changed from the vague "before `writeBundle` hooks are called" to explicitly state: > The cleanup happens before the `generateBundle` hook is called. This ensures that files created by plugins during `generateBundle` or `writeBundle` hooks are preserved. ### Added "In-depth" section Added a new section explaining the timing importance: - The cleanup occurs **before** the `generateBundle` hook - Files created by plugins in `generateBundle` or `writeBundle` hooks are **not** deleted - Guidance for advanced use cases with multiple outputs ## Why this matters Many plugins create files during the `generateBundle` hook (e.g., copying assets, generating additional files). Without clear documentation, users might be confused about why their plugin-generated files are or aren't being cleaned, leading to unexpected behavior in their build process. This update provides clarity on the execution order and helps users understand the plugin compatibility guarantees. ## References - Original feature: #6486 - Timing fix: #6647 - Issue comment: #6486 (comment) <!-- START COPILOT CODING AGENT SUFFIX --> <details> <summary>Original prompt</summary> > Read #6486 (comment) and #6647. Use concise words to describe the behavior and update related docs. Just point out new added behavior that #6647 emphasized and upadate the description in `/docs/options` </details> <!-- START COPILOT CODING AGENT TIPS --> --- ✨ Let Copilot coding agent [set things up for you](https://github.com/rolldown/rolldown/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.
14535d8 to
aa95c6a
Compare
IWANABETHATGUY
pushed a commit
that referenced
this pull request
Oct 27, 2025
…ity (#6682) ## Summary Updates the `output.cleanDir` documentation to clarify when directory cleanup occurs and how it affects plugin-generated files. ## Context PR #6486 introduced the `output.cleanDir` option to clean the output directory before emitting output. However, PR #6647 fixed an important timing issue where the cleanup was initially happening between `generateBundle` and `writeBundle` hooks, causing files created by plugins (like `@rollup/plugin-url` and `rollup-plugin-copy`) to be deleted. The fix moved the cleanup to occur **before** the `generateBundle` hook, ensuring all plugin-generated files are preserved. This documentation update clarifies this critical behavior for users. ## Changes ### Updated main description Changed from the vague "before `writeBundle` hooks are called" to explicitly state: > The cleanup happens before the `generateBundle` hook is called. This ensures that files created by plugins during `generateBundle` or `writeBundle` hooks are preserved. ### Added "In-depth" section Added a new section explaining the timing importance: - The cleanup occurs **before** the `generateBundle` hook - Files created by plugins in `generateBundle` or `writeBundle` hooks are **not** deleted - Guidance for advanced use cases with multiple outputs ## Why this matters Many plugins create files during the `generateBundle` hook (e.g., copying assets, generating additional files). Without clear documentation, users might be confused about why their plugin-generated files are or aren't being cleaned, leading to unexpected behavior in their build process. This update provides clarity on the execution order and helps users understand the plugin compatibility guarantees. ## References - Original feature: #6486 - Timing fix: #6647 - Issue comment: #6486 (comment) <!-- START COPILOT CODING AGENT SUFFIX --> <details> <summary>Original prompt</summary> > Read #6486 (comment) and #6647. Use concise words to describe the behavior and update related docs. Just point out new added behavior that #6647 emphasized and upadate the description in `/docs/options` </details> <!-- START COPILOT CODING AGENT TIPS --> --- ✨ Let Copilot coding agent [set things up for you](https://github.com/rolldown/rolldown/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.
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.
Summary
Updates the
output.cleanDirdocumentation to clarify when directory cleanup occurs and how it affects plugin-generated files.Context
PR #6486 introduced the
output.cleanDiroption to clean the output directory before emitting output. However, PR #6647 fixed an important timing issue where the cleanup was initially happening betweengenerateBundleandwriteBundlehooks, causing files created by plugins (like@rollup/plugin-urlandrollup-plugin-copy) to be deleted.The fix moved the cleanup to occur before the
generateBundlehook, ensuring all plugin-generated files are preserved. This documentation update clarifies this critical behavior for users.Changes
Updated main description
Changed from the vague "before
writeBundlehooks are called" to explicitly state:Added "In-depth" section
Added a new section explaining the timing importance:
generateBundlehookgenerateBundleorwriteBundlehooks are not deletedWhy this matters
Many plugins create files during the
generateBundlehook (e.g., copying assets, generating additional files). Without clear documentation, users might be confused about why their plugin-generated files are or aren't being cleaned, leading to unexpected behavior in their build process.This update provides clarity on the execution order and helps users understand the plugin compatibility guarantees.
References
output.clearDirto clean updirbefore build #6486generateBundleoutputs #6647output.clearDirto clean updirbefore build #6486 (comment)Original prompt
✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.