0
# Core CSS Purging
1

2
The main PurgeCSS class provides comprehensive CSS optimization functionality with selector extraction, matching, and removal operations.
3

4
## Capabilities
5

6
### PurgeCSS Class
7

8
Main class for CSS purging operations providing the primary API interface.
9

10
```typescript { .api }
11
/**
12
 * Class used to instantiate PurgeCSS and can then be used to purge CSS files.
13
 */
14
class PurgeCSS {
15
  options: Options;
16
  selectorsRemoved: Set<string>;
17
  removedNodes: postcss.Node[];
18
  variablesStructure: VariablesStructure;
19
}
20
```
21

22
### Primary Purge Method
23

24
Main method to remove unused CSS from stylesheets based on content analysis.
25

26
```typescript { .api }
27
/**
28
 * Remove unused CSS
29
 * @param userOptions - PurgeCSS options or path to the configuration file
30
 * @returns Promise resolving to array of purged CSS results
31
 */
32
purge(userOptions?: UserDefinedOptions | string): Promise<ResultPurge[]>;
33
```
34

35
**Usage Examples:**
36

37
```typescript
38
import { PurgeCSS } from "purgecss";
39

40
// Using options object
41
const purgeCSSResults = await new PurgeCSS().purge({
42
  content: ['index.html', '**/*.js', '**/*.html', '**/*.vue'],
43
  css: ['css/app.css']
44
});
45

46
// Using configuration file
47
const purgeCSSResults = await new PurgeCSS().purge('./purgecss.config.js');
48

49
// Using custom configuration file path
50
const purgeCSSResults = await new PurgeCSS().purge('./custom-purgecss.config.js');
51
```
52

53
### File-Based Selector Extraction
54

55
Extract selectors from content files using glob patterns or file paths.
56

57
```typescript { .api }
58
/**
59
 * Extract the selectors present in the files using a PurgeCSS extractor
60
 * @param files - Array of files path or glob pattern
61
 * @param extractors - Array of extractors
62
 * @returns Promise resolving to extracted selector sets
63
 */
64
extractSelectorsFromFiles(files: string[], extractors: Extractors[]): Promise<ExtractorResultSets>;
65
```
66

67
### String-Based Selector Extraction
68

69
Extract selectors from raw content strings with specified file extensions.
70

71
```typescript { .api }
72
/**
73
 * Extract the selectors present in the passed string using a PurgeCSS extractor
74
 * @param content - Array of content with raw strings and extensions
75
 * @param extractors - Array of extractors
76
 * @returns Promise resolving to extracted selector sets
77
 */
78
extractSelectorsFromString(content: RawContent[], extractors: Extractors[]): Promise<ExtractorResultSets>;
79
```
80

81
### CSS Processing
82

83
Get purged CSS from CSS sources using extracted selectors.
84

85
```typescript { .api }
86
/**
87
 * Get the purged version of the css based on the files
88
 * @param cssOptions - css options, files or raw strings
89
 * @param selectors - set of extracted css selectors
90
 * @returns Promise resolving to array of purged CSS results
91
 */
92
getPurgedCSS(cssOptions: Array<string | RawCSS>, selectors: ExtractorResultSets): Promise<ResultPurge[]>;
93
```
94

95
### AST Walking
96

97
Walk through CSS Abstract Syntax Tree and remove unused CSS rules.
98

99
```typescript { .api }
100
/**
101
 * Walk through the CSS AST and remove unused CSS
102
 * @param root - root node of the postcss AST
103
 * @param selectors - selectors used in content files
104
 */
105
walkThroughCSS(root: PostCSSRoot, selectors: ExtractorResultSets): void;
106
```
107

108
### Specialized Removal Methods
109

110
Remove specific types of unused CSS constructs.
111

112
```typescript { .api }
113
/**
114
 * Remove unused CSS variables
115
 */
116
removeUnusedCSSVariables(): void;
117

118
/**
119
 * Remove unused font-faces
120
 */
121
removeUnusedFontFaces(): void;
122

123
/**
124
 * Remove unused keyframes
125
 */
126
removeUnusedKeyframes(): void;
127
```
128

129
## Configuration Options
130

131
### UserDefinedOptions Interface
132

133
Main options interface for configuring PurgeCSS behavior.
134

135
```typescript { .api }
136
interface UserDefinedOptions {
137
  /** Array of content files/globs or raw content objects to analyze */
138
  content: Array<string | RawContent>;
139
  /** Array of CSS files/globs or raw CSS objects to purge */
140
  css: Array<string | RawCSS>;
141
  /** Default extractor function for content without specific extractor */
142
  defaultExtractor?: ExtractorFunction;
143
  /** Custom extractors for specific file types */
144
  extractors?: Array<Extractors>;
145
  /** Enable unused @font-face removal */
146
  fontFace?: boolean;
147
  /** Enable unused @keyframes removal */
148
  keyframes?: boolean;
149
  /** Output directory for purged CSS files */
150
  output?: string;
151
  /** Include rejected selectors in results */
152
  rejected?: boolean;
153
  /** Include rejected CSS content in results */
154
  rejectedCss?: boolean;
155
  /** Source map generation options */
156
  sourceMap?: boolean | (postcss.SourceMapOptions & { to?: string });
157
  /** Read CSS from stdin */
158
  stdin?: boolean;
159
  /** Output CSS to stdout */
160
  stdout?: boolean;
161
  /** Enable unused CSS variables removal */
162
  variables?: boolean;
163
  /** Safelist configuration for protected selectors */
164
  safelist?: UserDefinedSafelist;
165
  /** Blocklist configuration for forced removal */
166
  blocklist?: StringRegExpArray;
167
  /** Glob patterns to skip during content scanning */
168
  skippedContentGlobs?: Array<string>;
169
  /** Custom CSS attribute selectors to preserve */
170
  dynamicAttributes?: string[];
171
}
172
```
173

174
### Options Interface
175

176
Internal options interface with all properties defined (used internally by PurgeCSS).
177

178
```typescript { .api }
179
interface Options {
180
  content: Array<string | RawContent>;
181
  css: Array<string | RawCSS>;
182
  defaultExtractor: ExtractorFunction;
183
  extractors: Array<Extractors>;
184
  fontFace: boolean;
185
  keyframes: boolean;
186
  output?: string;
187
  rejected: boolean;
188
  rejectedCss: boolean;
189
  sourceMap: boolean | (postcss.SourceMapOptions & { to?: string });
190
  stdin: boolean;
191
  stdout: boolean;
192
  variables: boolean;
193
  safelist: Required<ComplexSafelist>;
194
  blocklist: StringRegExpArray;
195
  skippedContentGlobs: Array<string>;
196
  dynamicAttributes: string[];
197
}
198
```
199

200
## Result Types
201

202
### ResultPurge Interface
203

204
Result object returned by purge operations containing processed CSS and metadata.
205

206
```typescript { .api }
207
interface ResultPurge {
208
  /** Purged CSS content */
209
  css: string;
210
  /** Source map (empty if sourceMap inline option not set to false) */
211
  sourceMap?: string;
212
  /** Rejected CSS content (if rejectedCss option enabled) */
213
  rejectedCss?: string;
214
  /** Original file path (for file-based CSS) */
215
  file?: string;
216
  /** Array of rejected selectors (if rejected option enabled) */
217
  rejected?: string[];
218
}
219
```
220

221
## Content Input Types
222

223
```typescript { .api }
224
interface RawContent<T = string> {
225
  /** File extension for content type detection */
226
  extension: string;
227
  /** Raw content string */
228
  raw: T;
229
}
230

231
interface RawCSS {
232
  /** Raw CSS content string */
233
  raw: string;
234
  /** Optional name for the CSS content */
235
  name?: string;
236
}
237
```
238

239
## PostCSS Integration
240

241
```typescript { .api }
242
type PostCSSRoot = postcss.Root;
243
```