@rolldown/pluginutils

A utility library for building flexible, composable filter expressions that can be used in plugin hook filters of Rolldown/Vite/Rollup/Unplugin plugins.

Installation

1pnpm add @rolldown/pluginutils

Usage

Simple Filters

1import {
2  exactRegex,
3  makeIdFiltersToMatchWithQuery,
4  prefixRegex,
5} from '@rolldown/pluginutils';
6
7// Match exactly 'foo.js'
8const filter = exactRegex('foo.js');
9
10// Match any id starting with 'lib/'
11const prefix = prefixRegex('lib/');
12
13// Match ids with query params (e.g. 'foo.js?bar')
14const idFilters = makeIdFiltersToMatchWithQuery(['**/*.js', /\.ts$/]);
15
16// Usage in a plugin to define a hook filter
17const myPlugin = {
18  resolveId: {
19    filter: {
20      id: [exactRegex('MY_ID_TO_CHECK'), /some-other-regex/],
21    },
22    handler(id) {
23      // Your code here
24    },
25  },
26};

Composable Filters

[!WARNING] Composable filters are not yet supported in Vite, Rolldown-Vite or unplugin. They can be used in Rolldown plugins only.

1import { and, id, include, moduleType, query } from '@rolldown/pluginutils';
2
3// Build a filter expression
4const filterExpr = and(
5  id(/\.ts$/),
6  moduleType('ts'),
7  query('foo', true),
8);
9
10// Usage in a plugin to define a hook filter
11const myPlugin = {
12  transform: {
13    filter: [include(filterExpr)],
14    handler(code, id, options) {
15      // Your code here
16    },
17  },
18};

API Reference

Simple Filters

• exactRegex(str: string, flags?: string): RegExp — Matches the exact string.
• prefixRegex(str: string, flags?: string): RegExp — Matches values with the given prefix.
• makeIdFiltersToMatchWithQuery(input: string | RegExp | (string | RegExp)[]): string | RegExp | (string | RegExp)[] — Adapts filters to match ids with query params.

Composable Filters

• and(...exprs) / or(...exprs) / not(expr) — Logical composition of filter expressions.
• id(pattern, params?) — Filter by id (string or RegExp).
• moduleType(type) — Filter by module type (e.g. 'js', 'tsx', or 'json').
• code(pattern) — Filter by code content.
• query(key, pattern) — Filter by query parameter.
• include(expr) / exclude(expr) — Top-level include/exclude wrappers.
• queries(obj) — Compose multiple query filters.