0
# Configuration
1

2
Configuration management, default options, and utility functions for PurgeCSS operations.
3

4
## Capabilities
5

6
### Default Options
7

8
Pre-configured default options providing baseline PurgeCSS behavior.
9

10
```typescript { .api }
11
/**
12
 * Default PurgeCSS configuration options
13
 */
14
const defaultOptions: Options;
15
```
16

17
**Default Configuration Values:**
18

19
```typescript
20
const defaultOptions: Options = {
21
  css: [],
22
  content: [],
23
  defaultExtractor: (content: string): ExtractorResult =>
24
    content.match(/[A-Za-z0-9_-]+/g) || [],
25
  extractors: [],
26
  fontFace: false,
27
  keyframes: false,
28
  rejected: false,
29
  rejectedCss: false,
30
  sourceMap: false,
31
  stdin: false,
32
  stdout: false,
33
  variables: false,
34
  safelist: {
35
    standard: [],
36
    deep: [],
37
    greedy: [],
38
    variables: [],
39
    keyframes: [],
40
  },
41
  blocklist: [],
42
  skippedContentGlobs: [],
43
  dynamicAttributes: [],
44
};
45
```
46

47
### Configuration File Loading
48

49
Load PurgeCSS configuration from external files.
50

51
```typescript { .api }
52
/**
53
 * Load the configuration file from the path
54
 * @param configFile - Path of the config file (defaults to 'purgecss.config.js')
55
 * @returns The options from the configuration file
56
 * @throws Error if the configuration file cannot be imported
57
 */
58
function setOptions(configFile?: string): Promise<Options>;
59
```
60

61
**Usage Examples:**
62

63
```typescript
64
import { setOptions } from "purgecss";
65

66
// Load default config file (purgecss.config.js)
67
const options = await setOptions();
68

69
// Load custom config file
70
const customOptions = await setOptions('./my-purgecss.config.js');
71

72
// Use with PurgeCSS
73
const results = await new PurgeCSS().purge(options);
74
```
75

76
**Example Configuration File (`purgecss.config.js`):**
77

78
```javascript
79
module.exports = {
80
  content: ['src/**/*.html', 'src/**/*.js', 'src/**/*.vue'],
81
  css: ['dist/**/*.css'],
82
  fontFace: true,
83
  keyframes: true,
84
  variables: true,
85
  safelist: {
86
    standard: ['btn', 'navbar'],
87
    deep: [/^theme-/],
88
    greedy: [/^data-/]
89
  },
90
  extractors: [
91
    {
92
      extractor: (content) => content.match(/[A-Za-z0-9_:-]+/g) || [],
93
      extensions: ['vue']
94
    }
95
  ]
96
};
97
```
98

99
### Safelist Standardization
100

101
Utility function to normalize user-defined safelist configurations into consistent format.
102

103
```typescript { .api }
104
/**
105
 * Format the user defined safelist into a standardized safelist object
106
 * @param userDefinedSafelist - User defined safelist (array or complex object)
107
 * @returns Formatted safelist object with all properties defined
108
 */
109
function standardizeSafelist(
110
  userDefinedSafelist?: UserDefinedSafelist
111
): Required<ComplexSafelist>;
112
```
113

114
**Usage Examples:**
115

116
```typescript
117
import { standardizeSafelist } from "purgecss";
118

119
// Array format conversion
120
const standardized1 = standardizeSafelist(['btn', 'navbar']);
121
// Result: { standard: ['btn', 'navbar'], deep: [], greedy: [], variables: [], keyframes: [] }
122

123
// Complex object format
124
const standardized2 = standardizeSafelist({
125
  standard: ['btn'],
126
  deep: [/^theme-/]
127
});
128
// Result: { standard: ['btn'], deep: [/^theme-/], greedy: [], variables: [], keyframes: [] }
129
```
130

131
### Extractor Merging
132

133
Utility function for combining multiple extractor results into a single set.
134

135
```typescript { .api }
136
/**
137
 * Merge multiple extractor selectors into a single result set
138
 * @param extractors - Variable number of ExtractorResultDetailed or ExtractorResultSets
139
 * @returns Merged ExtractorResultSets containing all selectors
140
 */
141
function mergeExtractorSelectors(
142
  ...extractors: (ExtractorResultDetailed | ExtractorResultSets)[]
143
): ExtractorResultSets;
144
```
145

146
**Usage Example:**
147

148
```typescript
149
import { mergeExtractorSelectors, PurgeCSS } from "purgecss";
150

151
const purgeCSS = new PurgeCSS();
152

153
// Extract from different sources
154
const htmlSelectors = await purgeCSS.extractSelectorsFromFiles(
155
  ['src/**/*.html'], 
156
  htmlExtractors
157
);
158
const jsSelectors = await purgeCSS.extractSelectorsFromFiles(
159
  ['src/**/*.js'], 
160
  jsExtractors
161
);
162

163
// Merge all selectors
164
const allSelectors = mergeExtractorSelectors(htmlSelectors, jsSelectors);
165

166
// Use merged selectors for CSS purging
167
const results = await purgeCSS.getPurgedCSS(['styles/*.css'], allSelectors);
168
```
169

170
## Configuration Constants
171

172
### File and Annotation Constants
173

174
Built-in constants for configuration file names and CSS comment annotations.
175

176
```typescript { .api }
177
/** Default configuration file name */
178
const CONFIG_FILENAME = "purgecss.config.js";
179

180
/** CSS comment annotations for PurgeCSS control */
181
const IGNORE_ANNOTATION_CURRENT = "purgecss ignore current";
182
const IGNORE_ANNOTATION_NEXT = "purgecss ignore";
183
const IGNORE_ANNOTATION_START = "purgecss start ignore";
184
const IGNORE_ANNOTATION_END = "purgecss end ignore";
185

186
/** Error message for configuration loading failures */
187
const ERROR_CONFIG_FILE_LOADING = "Error loading the config file";
188
```
189

190
### CSS Ignore Annotations
191

192
PurgeCSS supports CSS comments for controlling selector processing:
193

194
```css
195
/* purgecss ignore current */
196
.btn-special {
197
  /* This rule will be ignored by PurgeCSS */
198
}
199

200
/* purgecss ignore */
201
.next-rule {
202
  /* The next rule after this comment will be ignored */
203
}
204

205
/* purgecss start ignore */
206
.ignored-block-1 {
207
  /* All rules between start and end ignore will be preserved */
208
}
209
.ignored-block-2 {
210
  /* This is also preserved */
211
}
212
/* purgecss end ignore */
213
```
214

215
## Advanced Configuration Patterns
216

217
### Environment-Specific Configuration
218

219
```typescript
220
// purgecss.production.config.js
221
module.exports = {
222
  content: ['dist/**/*.html', 'dist/**/*.js'],
223
  css: ['dist/**/*.css'],
224
  fontFace: true,
225
  keyframes: true,
226
  variables: true,
227
  rejected: false,
228
  rejectedCss: false
229
};
230

231
// purgecss.development.config.js  
232
module.exports = {
233
  content: ['src/**/*.html', 'src/**/*.js'],
234
  css: ['src/**/*.css'],
235
  fontFace: false,
236
  keyframes: false,
237
  variables: false,
238
  rejected: true,    // Log rejected selectors in development
239
  rejectedCss: true  // Include rejected CSS for debugging
240
};
241
```
242

243
### Dynamic Configuration
244

245
```typescript
246
import { setOptions, PurgeCSS } from "purgecss";
247

248
async function createDynamicConfig(environment: string) {
249
  const baseConfig = await setOptions('./base.config.js');
250
  
251
  if (environment === 'production') {
252
    return {
253
      ...baseConfig,
254
      fontFace: true,
255
      keyframes: true,
256
      variables: true,
257
      sourceMap: false
258
    };
259
  }
260
  
261
  return {
262
    ...baseConfig,
263
    rejected: true,
264
    rejectedCss: true,
265
    sourceMap: true
266
  };
267
}
268

269
const config = await createDynamicConfig(process.env.NODE_ENV);
270
const results = await new PurgeCSS().purge(config);
271
```
272

273
### Skip Patterns Configuration
274

275
```typescript
276
const options = {
277
  content: ['src/**/*'],
278
  css: ['dist/**/*.css'],
279
  skippedContentGlobs: [
280
    'src/vendor/**/*',      // Skip vendor files
281
    'src/**/*.min.js',      // Skip minified files
282
    'src/test/**/*',        // Skip test files
283
    'node_modules/**/*'     // Skip node_modules
284
  ]
285
};
286
```
287

288
This configuration prevents PurgeCSS from scanning certain files or directories that might contain irrelevant or problematic content for selector extraction.