0
# @rollup/pluginutils
1

2
A comprehensive set of utility functions commonly used by Rollup plugins. This package provides essential tools for plugin development including file filtering, path normalization, AST analysis, code generation, and pattern matching utilities.
3

4
## Package Information
5

6
- **Package Name**: @rollup/pluginutils
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @rollup/pluginutils --save-dev`
10
- **Requirements**: Node.js v14.0.0+ and Rollup v1.20.0+
11

12
## Core Imports
13

14
```typescript
15
import { createFilter, dataToEsm, makeLegalIdentifier } from "@rollup/pluginutils";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { createFilter, dataToEsm, makeLegalIdentifier } = require("@rollup/pluginutils");
22
```
23

24
Legacy default export (to be removed in future versions):
25

26
```javascript
27
import utils from "@rollup/pluginutils";
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { createFilter, addExtension, normalizePath } from "@rollup/pluginutils";
34

35
// Create a file filter for plugin processing
36
const filter = createFilter(
37
  ["src/**/*.js", "src/**/*.ts"], // include patterns
38
  ["src/**/*.test.*"], // exclude patterns
39
  { resolve: process.cwd() }
40
);
41

42
// Use in plugin transform hook
43
export default function myPlugin(options = {}) {
44
  return {
45
    resolveId(id) {
46
      // Add .js extension if missing
47
      return addExtension(id);
48
    },
49
    transform(code, id) {
50
      // Normalize path for cross-platform compatibility
51
      const normalizedId = normalizePath(id);
52
      
53
      // Only process files that match our filter
54
      if (!filter(normalizedId)) return;
55
      
56
      // Transform the code...
57
      return { code: transformedCode };
58
    }
59
  };
60
}
61
```
62

63
## Architecture
64

65
@rollup/pluginutils is organized around four main functional areas:
66

67
- **File Processing**: Path manipulation, extension handling, and include/exclude filtering
68
- **AST Analysis**: Scope tracking and variable name extraction for code analysis
69
- **Code Generation**: Identifier creation and data-to-module transformation
70
- **Pattern Matching**: Regular expression utilities for precise string matching
71

72
Each utility is designed to be lightweight, composable, and handle cross-platform concerns automatically.
73

74
## Capabilities
75

76
### File Processing
77

78
Essential utilities for handling file paths, extensions, and filtering in plugin workflows.
79

80
```typescript { .api }
81
function createFilter(
82
  include?: FilterPattern,
83
  exclude?: FilterPattern,
84
  options?: { resolve?: string | false | null }
85
): (id: string | unknown) => boolean;
86

87
function addExtension(filename: string, ext?: string): string;
88

89
function normalizePath(filename: string): string;
90

91
type FilterPattern = ReadonlyArray<string | RegExp> | string | RegExp | null;
92
```
93

94
[File Processing](./file-processing.md)
95

96
### AST Analysis
97

98
Tools for analyzing Abstract Syntax Trees, tracking variable scopes, and extracting assignment patterns.
99

100
```typescript { .api }
101
function attachScopes(ast: BaseNode, propertyName?: string): AttachedScope;
102

103
function extractAssignedNames(param: BaseNode): string[];
104

105
interface AttachedScope {
106
  parent?: AttachedScope;
107
  isBlockScope: boolean;
108
  declarations: { [key: string]: boolean };
109
  addDeclaration(node: BaseNode, isBlockDeclaration: boolean, isVar: boolean): void;
110
  contains(name: string): boolean;
111
}
112
```
113

114
[AST Analysis](./ast-analysis.md)
115

116
### Code Generation
117

118
Utilities for generating valid JavaScript code, identifiers, and ES modules from data structures.
119

120
```typescript { .api }
121
function makeLegalIdentifier(str: string): string;
122

123
function dataToEsm(data: unknown, options?: DataToEsmOptions): string;
124

125
interface DataToEsmOptions {
126
  compact?: boolean;
127
  includeArbitraryNames?: boolean;
128
  indent?: string;
129
  namedExports?: boolean;
130
  objectShorthand?: boolean;
131
  preferConst?: boolean;
132
}
133
```
134

135
[Code Generation](./code-generation.md)
136

137
### Regular Expression Utilities
138

139
Pattern matching utilities for creating precise RegExp patterns, commonly used in plugin hook filters.
140

141
```typescript { .api }
142
function exactRegex(str: string | string[], flags?: string): RegExp;
143

144
function prefixRegex(str: string | string[], flags?: string): RegExp;
145

146
function suffixRegex(str: string | string[], flags?: string): RegExp;
147
```
148

149
[Regular Expression Utilities](./regex-utilities.md)
150

151
## Types
152

153
Core type definitions used across the API:
154

155
```typescript { .api }
156
import type { BaseNode } from 'estree';
157

158
type FilterPattern = ReadonlyArray<string | RegExp> | string | RegExp | null;
159

160
interface AttachedScope {
161
  parent?: AttachedScope;
162
  isBlockScope: boolean;
163
  declarations: { [key: string]: boolean };
164
  addDeclaration(node: BaseNode, isBlockDeclaration: boolean, isVar: boolean): void;
165
  contains(name: string): boolean;
166
}
167

168
interface DataToEsmOptions {
169
  compact?: boolean;
170
  includeArbitraryNames?: boolean;
171
  indent?: string;
172
  namedExports?: boolean;
173
  objectShorthand?: boolean;
174
  preferConst?: boolean;
175
}
176
```
177

178
## Dependencies
179

180
- **@types/estree**: AST type definitions for JavaScript/TypeScript
181
- **estree-walker**: Tree traversal utilities for AST manipulation
182
- **picomatch**: Advanced glob pattern matching (v4.0.2+)