skip to content

When porting an in-house Rollup-style plugin to Vite 8, why add hook filters, when should load or transform return moduleType: 'js', and which Rollup hooks stop running?

level: seniorimportance: nice to knowfreq 3%

answer

  1. the bundler's core is native now
  2. crossing runtimes costs a call
  3. id, moduleType and code filters
  4. the extension sets the module type
  5. three hooks Rolldown never calls

basics

~20 s

In Vite 8, Rolldown calls JavaScript plugins from Rust, so hook filters let it skip unrelated modules. A load or transform turning another type into JavaScript should return moduleType: 'js'. shouldTransformCachedModule, resolveImportMeta and renderDynamicImport no longer run.

solid answer

~40 s

Vite 8 builds with Rolldown, whose core is Rust; every call into a JavaScript hook crosses between the two runtimes, so a `transform` that starts with `if (!id.endsWith('.md')) return` still costs one call per module. An object hook with `filter: { id: /\.md$/ }` lets Rolldown decide on the Rust side. `transform` filters can also match `moduleType` and `code`, while `resolveId` and `load` filter on `id` only, and `resolveId` needs a RegExp. Keep the in-handler check only if the plugin must also support Vite before 6.3. Rolldown infers a module's type from its id's extension, so a hook that turns another type into JavaScript returns `moduleType: 'js'`. Rolldown never calls `shouldTransformCachedModule`, `resolveImportMeta` or `renderDynamicImport`, Rollup's parallel hooks run sequentially, and assignments into the `bundle` object must become `this.emitFile()`.

code

typescript · 11 lines
typescript
import { defineConfig, withFilter } from 'vite'
import legacyMarkdown from './build/legacy-markdown-plugin'

export default defineConfig({
  plugins: [
    // Rolldown calls this Rollup-era plugin's transform only for articles
    withFilter(legacyMarkdown(), {
      transform: { id: /\/articles\/.*\.md$/ },
    }),
  ],
})

go deeper

for a junior

Recall that Vite 8 builds with Rolldown, a bundler written in Rust, and that most Rollup-style plugins still work with it.

for a middle

Explain what a hook filter is, which properties each hook can filter on, and why moduleType: 'js' matters when a hook outputs JavaScript from another type.

for a senior

Audit in-house plugins for missing filters, module types, unsupported hooks, bundle mutation and transformWithEsbuild, and compare their output against a Vite 7 build before switching.

for a principal

Plan the plugin side of a Vite 8 upgrade across many apps: which plugins to port, replace with built-in features or drop, and how to stage support for both majors.

## What changed under your plugin Vite 8 builds with **Rolldown** instead of Rollup, and its dependency optimizer uses Rolldown instead of esbuild. Rolldown keeps a Rollup-compatible plugin interface, so most plugins load unchanged. Its core, however, is Rust: each call into a JavaScript hook crosses between the two runtimes. Porting an in-house plugin is mostly about calling JavaScript less often, declaring what your hooks produce, and replacing a handful of Rollup features Rolldown does not have. The same plugin object keeps working in the dev server, where Vite's plugin container calls the hooks per request, so filters and module types matter under both commands, while the `bundle` changes affect only the build. ## Hook filters A **hook filter** lets the bundler decide on the Rust side whether to call a hook at all. Instead of entering `transform` only to return early for most modules, the plugin declares which modules it wants: ```ts transform: { filter: { id: /\.md$/ }, handler(code, id) { // only .md modules arrive here }, } ``` | Hook | Filterable properties | |---|---| | `resolveId` | `id`, as a RegExp, because it matches the raw specifier | | `load` | `id` | | `transform` | `id`, `moduleType`, `code` | - A `string` `id` is treated as a glob and a `RegExp` as a regular expression. - With both `include` and `exclude`, `exclude` wins; when several properties are given, all must match. - Vite supports filters since 6.3 and Rollup since 4.38; keep a duplicate check inside the handler only while older versions are still supported. - `withFilter(plugin, { transform: { id: /\/articles\/.*\.md$/ } })`, exported by `vite`, adds a filter to a third-party plugin without forking it. - Composable filter expressions from `@rolldown/pluginutils` (`and`, `or`, `not`) are not supported in Vite yet; the object form is. Choosing the property depends on what the plugin keys on: - **A file extension or folder:** an `id` RegExp, as above. - **A fixed virtual id:** `exactRegex('virtual:build-info')` or `prefixRegex('virtual:newsroom/')`, both exported by `@rolldown/pluginutils`. - **Syntax inside the file:** a `code` filter. Vite 8's migration guide wraps a decorator transform in `withFilter(…, { transform: { code: '@' } })` so it only runs on files that contain an `@`. ## `moduleType: 'js'` Rolldown gives each module a **module type**, inferred from its resolved id's extension. A hook that converts another type into JavaScript, such as a `.txt` file into `export default "…"`, should return `moduleType: 'js'` alongside its code, so Rolldown does not keep treating the output as the original type. Vite 8's migration guide flags this for plugin authors; a hook that only rewrites JavaScript needs nothing. ## Hooks and behaviours that differ - **Not called:** `shouldTransformCachedModule`, `resolveImportMeta` and `renderDynamicImport`. A plugin that depends on one of them needs another route. - **Parallel hooks run sequentially:** hooks that Rollup runs in parallel across plugins no longer overlap. - **The `bundle` object:** assigning `bundle[fileName] = …` in `generateBundle` is not supported, so emit files with `this.emitFile()`; the object is also not the same reference across hooks. - **esbuild is optional:** a plugin calling `transformWithEsbuild` needs `esbuild` installed by the project, and `transformWithOxc` is the replacement. - **Build-only plugins** can sit under `build.rolldownOptions.plugins`, which behaves like `enforce: 'post'` plus `apply: 'build'`. - **Cloning the bundle:** `structuredClone(bundle)` now throws; clone a shallow copy, `structuredClone({ ...bundle })`, instead. - **Stricter source maps:** Rolldown validates a plugin's map against its `sources` and `names`, so a map with a dangling reference that Rollup silently tolerated can now fail the build. - **Parsing helpers:** `parseAst` and `parseAstAsync` are deprecated in favour of `parseSync` and `parse`. - **Detection:** `this.meta.rolldownVersion` exists only on Rolldown-powered Vite, so a plugin that supports Vite 7 and 8 can branch on it. ## A porting checklist 1. Convert `resolveId`, `load` and `transform` to object hooks with filters. 2. Add `moduleType: 'js'` wherever a hook outputs JavaScript from another type. 3. Search the plugin for the three unsupported hooks and for writes into `bundle`. 4. Replace `transformWithEsbuild`, or add `esbuild` as a dev dependency. 5. Compare the Vite 8 build output with the Vite 7 one for an app that uses the plugin before rolling it out.

  • Why does the documentation still advise checking the id inside the handler when a filter is set?
    Only for backward compatibility. Vite before 6.3 and Rollup before 4.38 ignore `filter`, so on those versions the handler is called for every module and must reject unrelated ids itself. On Vite 8 alone the filter is enough, and the extra check only costs a little time inside calls that already matched.
  • How can one plugin package support both Vite 7 and Vite 8?
    Branch on `this.meta.rolldownVersion`, which is set only on Rolldown-powered Vite, for code that must differ, and use filtered object hooks, which both majors understand. Avoid the hooks Rolldown does not call, emit files with `this.emitFile()` instead of writing into `bundle`, and return `moduleType: 'js'` wherever content of another type is converted.

  • Hook filters are a Rolldown-only feature that Vite ignores.
  • An early return inside transform costs Vite 8 as little as a filter.
  • Every Rollup plugin works unchanged as a Vite 8 plugin.
  • Rollup's parallel hooks still run concurrently under Rolldown.
  • Assigning a new entry into the bundle object still emits a file.

Assumes Vite 8, which builds with Rolldown instead of Rollup; hook filters exist since Vite 6.3, but Vite 8's migration guide is where moduleType and the unsupported hooks are listed.