docs: add plugin hook filter compatibility and fallback guide #7138

Copilot · 2025-11-20T03:54:34Z

Developers moving to plugin hook filters lacked clarity on version support and how to write backward-compatible plugins.

Changes

Fallback Implementation

Integrated compatibility information into the Fallback Implementation section, documenting that plugin hook filters are supported in Rollup 4.38.0+, Vite 6.3.0+, and all versions of Rolldown.

Shows how to support older versions using both filter and handler checks:

export default function myPlugin() {
  return {
    name: 'my-plugin',
    transform: {
      filter: { id: /\.data$/ },  // Used by newer versions
      handler(code, id) {
        if (!id.endsWith('.data')) return null;  // Fallback for older versions
        return transformedCode;
      }
    }
  }
}

Screenshots

Updated documentation structure:

Fallback Implementation with integrated compatibility info:

Fixes Add info/example about making sure that plugin hook filters work #5337

Original prompt

This section details on the original issue you should resolve

<issue_title>Add info/example about making sure that plugin hook filters work</issue_title>
<issue_description>When moving to plugin hook filters, I've seen multiple people wondering whether things work expected (with both, Rolldown but also tools like Rollup or Vite).
It would be great to document a way (likely adding assertions in hooks) so developers can verify the hooks work as they'd expect.</issue_description>

<agent_instructions>In "Plugin hook filters", clarify which version plugin hook filters are supported and add a section to describe how to write a fallback implementation for it. It is supported by Rollup 4.38.0+ and Vite 6.3.0+.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

Fixes Add info/example about making sure that plugin hook filters work #5337

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

graphite-app · 2025-11-20T03:54:39Z

How to use the Graphite Merge Queue

Add 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.}

netlify · 2025-11-20T03:55:21Z

✅ Deploy Preview for rolldown-rs ready!

Name	Link
🔨 Latest commit	`f87cb15`
🔍 Latest deploy log	https://app.netlify.com/projects/rolldown-rs/deploys/6925357fd4bfcb000836d60a
😎 Deploy Preview	https://deploy-preview-7138--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.

docs/apis/plugin-hook-filters.md

sapphi-red · 2025-11-20T06:02:54Z

@TheAlexLichter Does this match what you were thinking in #5337 ?

Copilot

Pull Request Overview

This PR adds comprehensive documentation on plugin hook filter compatibility and backward-compatible plugin implementation. It addresses developer concerns about version support and provides practical guidance for writing plugins that work across different tool versions.

Added version compatibility information (Rollup 4.38.0+, Vite 6.3.0+, all Rolldown versions)
Provided a "Fallback Implementation" section with a complete code example showing how to support both new and old versions
Included best practices tip about keeping filter patterns and internal checks synchronized

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/apis/plugin-hook-filters.md

hyf0

If they're using moduleType filter, being compatible is impossible.

We should introduce the concept of Rolldown only and Rollup compatible plugin.

Guide/Plugin guide around rolldown should written with considering Rolldown only plugin in mind instead of being compatible in mind. And we have a being comaptible version to clarify these details.

The current content arragement seems to mix up these two orientation and will bring bad dx for those rolldown-only users.

@TheAlexLichter cc

docs/apis/plugin-hook-filters.md

TheAlexLichter · 2025-11-21T09:58:08Z

@hyf0 Then let's also add what people can't use when using the compat version (e.g. module types)

sapphi-red · 2025-11-21T10:44:15Z

docs: add plugin hook filter compatibility and fallback guide #7138 👈 (View in Graphite)
main

How to use the Graphite Merge Queue

Add 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.

sapphi-red · 2025-11-21T10:46:20Z

I've updated based on the comments.

sapphi-red · 2025-11-21T10:47:32Z

Guide/Plugin guide around rolldown should written with considering Rolldown only plugin in mind instead of being compatible in mind. And we have a being comaptible version to clarify these details.

I think it is currently written in this way. The section is clearly separated.

graphite-app · 2025-11-25T04:49:50Z

Merge activity

Nov 25, 4:49 AM UTC: sapphi-red added this pull request to the Graphite merge queue.
Nov 25, 4:52 AM UTC: Merged by the Graphite merge queue.

Developers moving to plugin hook filters lacked clarity on version support and how to write backward-compatible plugins. ## Changes ### Fallback Implementation Integrated compatibility information into the Fallback Implementation section, documenting that plugin hook filters are supported in Rollup 4.38.0+, Vite 6.3.0+, and all versions of Rolldown. Shows how to support older versions using both filter and handler checks: ```js export default function myPlugin() { return { name: 'my-plugin', transform: { filter: { id: /\.data$/ }, // Used by newer versions handler(code, id) { if (!id.endsWith('.data')) return null; // Fallback for older versions return transformedCode; } } } } ``` ## Screenshots **Updated documentation structure:** <img src="https://github.com/user-attachments/assets/bfe39e0c-5145-43d5-a5b1-55cecbece698"> **Fallback Implementation with integrated compatibility info:** <img src="https://github.com/user-attachments/assets/d91533e9-10a5-4847-aac6-d5260e9a9b3e"> - Fixes #5337  <details> <summary>Original prompt</summary> > > ---- > > *This section details on the original issue you should resolve* > > <issue_title>Add info/example about making sure that plugin hook filters work</issue_title> > <issue_description>When moving to [plugin hook filters](https://rolldown.rs/apis/plugin-hook-filters), I've seen multiple people wondering whether things work expected (with both, Rolldown but also tools like Rollup or Vite). > It would be great to document a way (likely adding assertions in hooks) so developers can verify the hooks work as they'd expect.</issue_description> > > <agent_instructions>In "Plugin hook filters", clarify which version plugin hook filters are supported and add a section to describe how to write a fallback implementation for it. It is supported by Rollup 4.38.0+ and Vite 6.3.0+.</agent_instructions> > > ## Comments on the Issue (you are @copilot in this section) > > <comments> > </comments> > </details> - Fixes #5337  --- ✨ 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

## [1.0.0-beta.52] - 2025-11-26 💥 Breaking Change - Change `output.generatedCode.profilerNames` default to `false` 🔧 Vite-Style TypeScript Configuration - Rolldown now supports Vite-style automatic tsconfig resolution. Use `tsconfig: true` to enable auto-discovery mode where each module finds its nearest `tsconfig.json`. See more details [here](https://rolldown.rs/options/tsconfig) ⚙️ Upgraded to oxc v0.99.0 - Add `TSGlobalDeclaration` type - More details: https://github.com/oxc-project/oxc/releases/tag/crates_v0.99.0 ### 💥 BREAKING CHANGES - change `output.generatedCode.profilerNames` default to false (#7139) by @Copilot ### 🚀 Features - support vite-style tsconfig resolution (#6873) by @shulaoda - rolldown: oxc v0.99.0 (#7165) by @camc314 - browser: export `plugins` (#7210) by @sxzz - rolldown_plugin_vite_css_post: add `inline` parameter to `cssMinify` callback (#7191) by @shulaoda - rolldown_plugin_vite_build_import_analysis: implement `render_chunk` to replace `__VITE_IS_MODERN__` flag (#7178) by @shulaoda - rolldown_plugin_utils: optimize SVG data URL encoding (#7156) by @shulaoda - dev: replace `DevEngine::hasLatestBuildOutput` with `DevEngine::getBundleState` (#7145) by @sapphi-red - rolldown_plugin_vite_asset_import_meta_url: support `@vite-ignore` comment (#7141) by @shulaoda - rolldown_plugin_vite_asset_import_meta_url: implement static URL processing (#7140) by @shulaoda - rolldown_plugin_vite_asset_import_meta_url: align `asset_resolver` logic (#7137) by @shulaoda - rolldown_plugin_vite_asset_import_meta_url: align `try_fs_resolve` logic (#7136) by @shulaoda - rolldown_plugin_vite_asset_import_meta_url: validate relative paths (#7120) by @shulaoda - export `viteAssetImportMetaUrlPlugin` and add dynamic URL tests (#7119) by @shulaoda ### 🐛 Bug Fixes - watch overwrite rename event on linux (#7201) by @sapphi-red - preserve name for parenthesized anonymous default exports and arrow functions with keepNames (#7159) by @Copilot - rolldown_plugin_vite_html: add missing async attribute for inlined entry scripts (#7202) by @shulaoda - respect target setting in DCE to prevent modern syntax generation (#7128) by @Copilot - rolldown_plugin_vite_html: add semicolon to import statement in CSS removal (#7200) by @shulaoda - rolldown_plugin_vite_html: use correct CSS asset filename in HTML injection (#7199) by @shulaoda - rolldown_plugin_vite_css_post: handle scoped package names in lib CSS filename (#7198) by @shulaoda - rolldown_plugin_vite_html: use patched `html5gum` with correct span tracking (#7193) by @shulaoda - rolldown_plugin_vite_html: handle HTML strings in script tags correctly (#7192) by @shulaoda - handle JSON import namespace property access correctly (#7190) by @IWANABETHATGUY - only include runtime helpers from included modules (#7183) by @IWANABETHATGUY - rolldown_plugin_vite_html: normalize paths to use forward slashes in `original_file_name` (#7175) by @shulaoda - rolldown_plugin_vite_css_post: use `filename` instead of `reference_id` for imported assets (#7174) by @shulaoda - rolldown_plugin_vite_css_post: correct regex escaping in pure CSS chunk pruning (#7173) by @shulaoda - rolldown_plugin_vite_html: use correct dependency path for modulepreload links (#7172) by @shulaoda - update cur_stmt_index when processing top level statements (#7157) by @IWANABETHATGUY - rolldown_plugin_utils: strip leading character from public asset URL (#7170) by @shulaoda - rolldown_plugin_vite_html: use correct `public_base` for `html_result_map` key (#7169) by @shulaoda - rolldown_plugin_utils: correct runtime handling and escape single quotes in asset paths (#7168) by @shulaoda - rolldown_plugin_utils: prevent data race in `file_to_url` cache (#7166) by @shulaoda - rolldown_plugin_vite_asset_import_meta_url: correct glob pattern and query string handling in dynamic URLs (#7162) by @shulaoda - rolldown_plugin_vite_css_post: use correct start position in magic string updates (#7158) by @shulaoda - data race in `FileEmitter::emit_file` causing duplicate asset emissions (#7164) by @shulaoda - dev: watch files even if the build failed (#7149) by @sapphi-red - rolldown_plugin_utils: always use base64 encoding for data URLs (#7148) by @shulaoda - preserve "default" name for anonymous default exports with keepNames (#7151) by @Copilot - correctly handle cjs json module as entry point (#7147) by @IWANABETHATGUY - rolldown_plugin_utils: correct `reference_id` parsing in `render_asset_url_in_js` (#7143) by @shulaoda - rolldown_plugin_vite_asset_import_meta_url: exclude quotes from URL span (#7142) by @shulaoda - rolldown_plugin_vite_asset_import_meta_url: use template literal for glob result indexing (#7134) by @shulaoda - tree shake unused dynamic entry when `inlineDynamicImports` is enabled (#7129) by @IWANABETHATGUY - correct return value of `parse` / `parseSync` functions (#7127) by @sapphi-red ### 🚜 Refactor - rolldown_plugin_vite_transform: use `oxc_resolver` for tsconfig discovery (#7220) by @shulaoda - rolldown_plugin_vite_resolve: use `resolve_file` for tsconfig discovery (#7216) by @shulaoda - rolldown_plugin_utils: remove redundant `ViteMetadata::get_or_insert_default()` (#7189) by @shulaoda - rolldown_plugin_utils: simplify `ViteMetadata::get()` to always return a value (#7188) by @shulaoda - rolldown_utils: add `guess_mime_skip_utf8_check` for binary assets (#7161) by @shulaoda - rolldown_plugin_utils: extract asset URL parsing into `AssetUrlIter` (#7144) by @shulaoda - store pattern name in FilenameTemplate (#7132) by @IWANABETHATGUY ### 📚 Documentation - tsconfig: document auto-discovery mode and improve structure (#7228) by @shulaoda - add plugin hook filter compatibility and fallback guide (#7138) by @Copilot - update top level navigation (#7092) by @mdong1909 ### 🧪 Testing - add tsconfig include/exclude/files matching test cases (#6899) by @shulaoda - vite-tests: run `playwright install` in case playwright binary is missing (#7226) by @sapphi-red - watch: close watcher when an error occured in the test cases (#7225) by @sapphi-red - watch: reject `waitBuildFinished` if `ERROR` event occurs (#7224) by @sapphi-red ### ⚙️ Miscellaneous Tasks - example: revert accidental changes to basic-typescript (#7227) by @shulaoda - deps: update oxc apps (#7212) by @renovate[bot] - deps: update rust crates (#7204) by @renovate[bot] - deps: update `oxc_resolver_napi` to 11.14.0 (#7217) by @shulaoda - deps: update oxc_resolver (#6909) by @shulaoda - deps: update dependency glob to v13 (#7208) by @renovate[bot] - deps: update actions/checkout action to v6 (#7207) by @renovate[bot] - deps: update npm packages (#7206) by @renovate[bot] - deps: update github-actions (#7205) by @renovate[bot] - add missing status code comment (#7185) by @iiio2 - deps: update dependency oxlint-tsgolint to v0.8.1 (#7197) by @renovate[bot] - rust: add more tracing log for hmr + dev logic (#7179) by @hyf0 - deps: update dependency oxlint-tsgolint to v0.8.0 (#7167) by @renovate[bot] - deps: update dependency oxlint-tsgolint to v0.7.3 (#7133) by @renovate[bot] - merge similar inlineDynamicImports test case (#7131) by @IWANABETHATGUY - deps: update `rolldown-plugin-dts` to 0.18.0 (#7125) by @shulaoda Co-authored-by: shulaoda <[email protected]>

Copilot AI assigned Copilot and sapphi-red Nov 20, 2025

Copilot started work on behalf of sapphi-red November 20, 2025 03:55 View session

Copilot AI changed the title ~~[WIP] Add documentation for verifying plugin hook filters~~ docs: add plugin hook filter compatibility and verification guide Nov 20, 2025

Copilot AI requested a review from sapphi-red November 20, 2025 04:06

Copilot finished work on behalf of sapphi-red November 20, 2025 04:06

sapphi-red reviewed Nov 20, 2025

View reviewed changes

docs/apis/plugin-hook-filters.md Outdated Show resolved Hide resolved

docs/apis/plugin-hook-filters.md Outdated Show resolved Hide resolved

Copilot started work on behalf of sapphi-red November 20, 2025 05:46 View session

Copilot AI changed the title ~~docs: add plugin hook filter compatibility and verification guide~~ docs: add plugin hook filter compatibility and fallback guide Nov 20, 2025

Copilot finished work on behalf of sapphi-red November 20, 2025 05:53

Copilot AI requested a review from sapphi-red November 20, 2025 05:53

sapphi-red approved these changes Nov 20, 2025

View reviewed changes

sapphi-red marked this pull request as ready for review November 20, 2025 06:03

Copilot AI review requested due to automatic review settings November 20, 2025 06:03

Copilot started reviewing on behalf of sapphi-red November 20, 2025 06:03 View session

Copilot finished reviewing on behalf of sapphi-red November 20, 2025 06:05

Copilot AI reviewed Nov 20, 2025

View reviewed changes

docs/apis/plugin-hook-filters.md Outdated Show resolved Hide resolved

graphite-app bot reviewed Nov 20, 2025

View reviewed changes

docs/apis/plugin-hook-filters.md Show resolved Hide resolved

hyf0 requested a review from TheAlexLichter November 20, 2025 17:04

hyf0 approved these changes Nov 20, 2025

View reviewed changes

TheAlexLichter requested changes Nov 21, 2025

View reviewed changes

docs/apis/plugin-hook-filters.md Outdated Show resolved Hide resolved

docs/apis/plugin-hook-filters.md Show resolved Hide resolved

docs/apis/plugin-hook-filters.md Show resolved Hide resolved

sapphi-red force-pushed the copilot/add-plugin-hook-filter-documentation branch from 4315174 to c31d0ed Compare November 21, 2025 10:43

sapphi-red requested a review from TheAlexLichter November 21, 2025 10:47

TheAlexLichter approved these changes Nov 23, 2025

View reviewed changes

graphite-app bot force-pushed the copilot/add-plugin-hook-filter-documentation branch from c31d0ed to f87cb15 Compare November 25, 2025 04:50

graphite-app bot merged commit f87cb15 into main Nov 25, 2025
25 checks passed

graphite-app bot deleted the copilot/add-plugin-hook-filter-documentation branch November 25, 2025 04:52

sapphi-red mentioned this pull request Nov 25, 2025

Add info/example about making sure that plugin hook filters work #5337

Closed

This was referenced Nov 26, 2025

release: v1.0.0-beta.52 #7223

Closed

release: v1.0.0-beta.52 #7229

Merged

docs: add plugin hook filter compatibility and fallback guide #7138

docs: add plugin hook filter compatibility and fallback guide #7138

Conversation

Copilot AI commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Fallback Implementation

Screenshots

Comments on the Issue (you are @copilot in this section)

Uh oh!

graphite-app bot commented Nov 20, 2025

How to use the Graphite Merge Queue

Uh oh!

netlify bot commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for rolldown-rs ready!

Uh oh!

Uh oh!

Uh oh!

sapphi-red commented Nov 20, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

hyf0 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

TheAlexLichter commented Nov 21, 2025

Uh oh!

sapphi-red commented Nov 21, 2025

How to use the Graphite Merge Queue

Uh oh!

sapphi-red commented Nov 21, 2025

Uh oh!

sapphi-red commented Nov 21, 2025

Uh oh!

graphite-app bot commented Nov 25, 2025 • edited 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!

4 participants

Copilot AI commented Nov 20, 2025 •

edited

Loading

netlify bot commented Nov 20, 2025 •

edited

Loading

hyf0 left a comment •

edited

Loading

graphite-app bot commented Nov 25, 2025 •

edited

Loading