Spaces:
Sleeping
Sleeping
File size: 6,177 Bytes
391a73c | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 | # @rolldown/pluginutils [](https://npmx.dev/package/@rolldown/pluginutils)
Plugin utilities for [Rolldown](https://rolldown.rs).
Includes regex helpers for plugin hook filters, composable filter expressions, and a helper for filtering out Vite-serve-only plugins.
## Install
```bash
pnpm add -D @rolldown/pluginutils
```
## Usage
```ts
import { exactRegex, prefixRegex, makeIdFiltersToMatchWithQuery } from '@rolldown/pluginutils'
```
All filter helpers are also exposed via the `/filter` subpath:
```ts
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.
```ts
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.
```ts
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.
```ts
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](https://rolldown.rs/apis/plugin-api/hook-filters#composable-filters) 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.
```ts
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.
```ts
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
|