0
# Filter System
1

2
Module filtering functionality for selective bundle analysis based on bundle names and file patterns.
3

4
```typescript
5
import { createFilter, Filter } from "rollup-plugin-visualizer";
6
```
7

8
## Capabilities
9

10
### Create Filter Function
11

12
Creates a filtering function for selective module inclusion/exclusion during analysis.
13

14
```typescript { .api }
15
/**
16
 * Creates a filtering function for selective module analysis
17
 * @param include - Patterns for modules to include (if empty, includes all by default)
18
 * @param exclude - Patterns for modules to exclude (takes precedence over include)
19
 * @returns Function that tests whether a module should be included
20
 */
21
function createFilter(
22
  include: Filter | Filter[] | undefined,
23
  exclude: Filter | Filter[] | undefined
24
): (bundleId: string, id: string) => boolean;
25
```
26

27
The `createFilter` function creates a predicate function that determines whether a given module should be included in the analysis. It follows these rules:
28

29
1. If `exclude` patterns match, the module is excluded (takes precedence)
30
2. If `include` patterns are specified and match, the module is included
31
3. If no `include` patterns are specified, all modules are included by default
32
4. If `include` patterns are specified but don't match, the module is excluded
33

34
**Usage Example:**
35

36
```typescript
37
import { createFilter } from "rollup-plugin-visualizer";
38

39
// Create filter that excludes node_modules but includes specific files
40
const filter = createFilter(
41
  [
42
    { file: "src/**/*.ts" },    // Include all TypeScript files in src
43
    { file: "lib/**/*.js" }     // Include all JavaScript files in lib
44
  ],
45
  [
46
    { file: "node_modules/**" }, // Exclude all node_modules
47
    { bundle: "test-*" }        // Exclude test bundles
48
  ]
49
);
50

51
// Test the filter
52
console.log(filter("main.js", "src/index.ts"));     // true
53
console.log(filter("main.js", "node_modules/foo")); // false
54
console.log(filter("test-bundle.js", "src/app.ts")); // false
55
```
56

57
### Filter Configuration
58

59
Filter configuration objects for specifying inclusion/exclusion patterns.
60

61
```typescript { .api }
62
/**
63
 * Filter configuration object for bundle and file patterns
64
 */
65
type Filter = {
66
  /** Bundle name pattern (glob pattern, optional) */
67
  bundle?: string | null | undefined;
68
  /** File path pattern (glob pattern, optional) */
69
  file?: string | null | undefined;
70
};
71
```
72

73
Filter objects can specify patterns for either bundle names, file paths, or both. Patterns use glob syntax via the picomatch library.
74

75
**Pattern Examples:**
76

77
```typescript
78
// File-only patterns (most common)
79
{ file: "src/**/*.ts" }          // All TypeScript files in src directory
80
{ file: "**/index.js" }          // All index.js files anywhere
81
{ file: "node_modules/**" }      // All files in node_modules
82

83
// Bundle-only patterns
84
{ bundle: "vendor-*" }           // Bundles starting with "vendor-"
85
{ bundle: "*.min.js" }           // Minified bundles
86

87
// Combined patterns (both must match)
88
{ 
89
  bundle: "main-*.js",           // Bundle name must match pattern
90
  file: "src/**/*.ts"            // AND file path must match pattern
91
}
92
```
93

94
### Filter Usage in Plugin
95

96
Integration of filters with the main visualizer plugin.
97

98
```typescript { .api }
99
interface PluginVisualizerOptions {
100
  /** Inclusion filters - if specified, only matching modules are included */
101
  include?: Filter | Filter[];
102
  /** Exclusion filters - matching modules are excluded (takes precedence) */
103
  exclude?: Filter | Filter[];
104
}
105
```
106

107
Filters are applied during the bundle analysis phase to selectively include or exclude modules from the visualization.
108

109
**Plugin Usage Examples:**
110

111
```typescript
112
import { visualizer } from "rollup-plugin-visualizer";
113

114
// Exclude node_modules and test files
115
visualizer({
116
  exclude: [
117
    { file: "node_modules/**" },
118
    { file: "**/*.test.js" },
119
    { file: "**/*.spec.js" }
120
  ]
121
})
122

123
// Only include source files
124
visualizer({
125
  include: [
126
    { file: "src/**" },
127
    { file: "lib/**" }
128
  ]
129
})
130

131
// Complex filtering: include source but exclude specific bundles
132
visualizer({
133
  include: [
134
    { file: "src/**/*.{js,ts}" }
135
  ],
136
  exclude: [
137
    { bundle: "polyfill-*" },
138
    { file: "src/**/*.test.ts" }
139
  ]
140
})
141

142
// Bundle-specific analysis
143
visualizer({
144
  include: [
145
    { bundle: "main.js", file: "**" }  // Only analyze main.js bundle
146
  ]
147
})
148
```
149

150
### Advanced Filtering Patterns
151

152
Complex filtering scenarios and pattern combinations.
153

154
**Exclude Strategy (Recommended):**
155
```typescript
156
// Start with everything, exclude what you don't want
157
visualizer({
158
  exclude: [
159
    { file: "node_modules/**" },      // External dependencies
160
    { file: "**/*.test.{js,ts}" },    // Test files
161
    { file: "**/*.spec.{js,ts}" },    // Spec files  
162
    { file: "**/dist/**" },           // Built files
163
    { bundle: "vendor-*" }            // Vendor bundles
164
  ]
165
})
166
```
167

168
**Include Strategy:**
169
```typescript
170
// Explicitly specify what to include
171
visualizer({
172
  include: [
173
    { file: "src/**/*.{js,ts,jsx,tsx}" }, // Source files only
174
    { file: "lib/**/*.js" }                // Library files
175
  ]
176
})
177
```
178

179
**Per-Bundle Analysis:**
180
```typescript
181
// Analyze specific bundles separately
182
visualizer({
183
  filename: 'main-bundle-stats.html',
184
  include: [{ bundle: "main.js" }]
185
})
186
```
187

188
**Path Normalization:**
189
The filter system works with normalized paths, so patterns should use forward slashes regardless of the operating system. The `projectRoot` option affects how paths are normalized before filtering.