@rolldown/pluginutils

@rolldown/pluginutils

Plugin utilities for Rolldown.

Includes regex helpers for plugin hook filters, composable filter expressions, and a helper for filtering out Vite-serve-only plugins.

Install

pnpm add -D @rolldown/pluginutils

Usage

import { exactRegex, prefixRegex, makeIdFiltersToMatchWithQuery } from '@rolldown/pluginutils'

All filter helpers are also exposed via the /filter subpath:

import { and, or, id, include } from '@rolldown/pluginutils/filter'

Regex helpers

exactRegex

• Type: (str: string, flags?: string) => RegExp

Constructs a RegExp that matches the exact string specified. Useful as a plugin hook filter.

import { exactRegex } from '@rolldown/pluginutils'

const plugin = {
  name: 'plugin',
  resolveId: {
    filter: { id: exactRegex('foo') },
    handler(id) {}, // only called for `foo`
  },
}

prefixRegex

• Type: (str: string, flags?: string) => RegExp

Constructs a RegExp that matches values starting with the specified prefix.

import { prefixRegex } from '@rolldown/pluginutils'

const plugin = {
  name: 'plugin',
  resolveId: {
    filter: { id: prefixRegex('foo') },
    handler(id) {}, // called for IDs starting with `foo`
  },
}

makeIdFiltersToMatchWithQuery

• Type: (input: string | RegExp | (string | RegExp)[]) => string | RegExp | (string | RegExp)[]

Converts an id filter so that it also matches ids that include a query string.

import { makeIdFiltersToMatchWithQuery } from '@rolldown/pluginutils'

const plugin = {
  name: 'plugin',
  transform: {
    filter: { id: makeIdFiltersToMatchWithQuery(['**/*.js', /\.ts$/]) },
    // Matches:
    //   foo.js, foo.js?foo, foo.txt?foo.js,
    //   foo.ts, foo.ts?foo, foo.txt?foo.ts
    handler(code, id) {},
  },
}

Composable filters

Composable filter expressions for use cases where a simple id/include/exclude is not enough. For example, when a plugin needs to combine id, moduleType, code, and query conditions.

import { and, code, id, include, interpreter, moduleType, or } from '@rolldown/pluginutils'

const expr = include(and(or(id(/\.tsx?$/), id(/\.jsx?$/)), moduleType('tsx'), code(/import React/)))

interpreter(expr, sourceCode, sourceId, 'tsx') // boolean

Builders

Builder	Description
and(...exprs)	All operands must match.
or(...exprs)	At least one operand must match.
not(expr)	Negates the operand.
id(pattern, params?)	Match the module id. pattern is string or RegExp. params.cleanUrl strips the query/hash before matching.
importerId(pattern, params?)	Match the importer's id. Same shape as id.
moduleType(type)	Match Rolldown's module type ('js', 'jsx', 'ts', 'tsx', 'json', 'text', 'base64', 'dataurl', 'binary', 'empty', or a custom string).
code(pattern)	Match the module source. string matches with includes; RegExp with test.
query(key, pattern)	Match a single query parameter. pattern is boolean (key presence/truthiness), string (exact value), or RegExp (value pattern).
queries(obj)	Shorthand for and(...) over multiple query entries.
include(expr)	Top-level wrapper marking expr as an inclusion rule.
exclude(expr)	Top-level wrapper marking expr as an exclusion rule.

interpreter

• Type: (exprs, code?, id?, moduleType?, importerId?) => boolean

Evaluates one or more top-level expressions against the given inputs. Returns true when at least one include matches and no exclude matches; when no include is present, defaults to true unless an exclude matches.

The argument required by each expression must be provided. For example, evaluating an id(...) expression without passing id will throw.

filterVitePlugins

• Type: <T>(plugins: T | T[] | null | undefined | false) => T[]

Removes Vite plugins that target the dev server (apply: 'serve') from a (possibly nested) plugin array. Plugins whose apply is a function are invoked with a command: 'build' context to decide. Useful when reusing a Vite plugin array inside a Rolldown config.

import { defineConfig } from 'rolldown'
import { filterVitePlugins } from '@rolldown/pluginutils'
import viteReact from '@vitejs/plugin-react'

export default defineConfig({
  plugins: filterVitePlugins([
    viteReact(),
    {
      name: 'dev-only',
      apply: 'serve', // filtered out
      // ...
    },
  ]),
})

License

MIT