| 1 | /**
|
| 2 | * Core package of PurgeCSS
|
| 3 | *
|
| 4 | * Contains the core methods to analyze the files, remove unused CSS.
|
| 5 | *
|
| 6 | * @packageDocumentation
|
| 7 | */
|
| 8 |
|
| 9 | import * as postcss from 'postcss';
|
| 10 |
|
| 11 | /* Excluded from this release type: AtRules */
|
| 12 |
|
| 13 | /**
|
| 14 | * @public
|
| 15 | */
|
| 16 | export declare type ComplexSafelist = {
|
| 17 | standard?: StringRegExpArray;
|
| 18 | /**
|
| 19 | * You can safelist selectors and their children based on a regular
|
| 20 | * expression with `safelist.deep`
|
| 21 | *
|
| 22 | * @example
|
| 23 | *
|
| 24 | * ```ts
|
| 25 | * const purgecss = await new PurgeCSS().purge({
|
| 26 | * content: [],
|
| 27 | * css: [],
|
| 28 | * safelist: {
|
| 29 | * deep: [/red$/]
|
| 30 | * }
|
| 31 | * })
|
| 32 | * ```
|
| 33 | *
|
| 34 | * In this example, selectors such as `.bg-red .child-of-bg` will be left
|
| 35 | * in the final CSS, even if `child-of-bg` is not found.
|
| 36 | *
|
| 37 | */
|
| 38 | deep?: RegExp[];
|
| 39 | greedy?: RegExp[];
|
| 40 | variables?: StringRegExpArray;
|
| 41 | keyframes?: StringRegExpArray;
|
| 42 | };
|
| 43 |
|
| 44 | /**
|
| 45 | * @public
|
| 46 | */
|
| 47 | export declare const defaultOptions: Options;
|
| 48 |
|
| 49 | /**
|
| 50 | * @public
|
| 51 | */
|
| 52 | export declare type ExtractorFunction<T = string> = (content: T) => ExtractorResult;
|
| 53 |
|
| 54 | /**
|
| 55 | * @public
|
| 56 | */
|
| 57 | export declare type ExtractorResult = ExtractorResultDetailed | string[];
|
| 58 |
|
| 59 | /**
|
| 60 | * @public
|
| 61 | */
|
| 62 | export declare interface ExtractorResultDetailed {
|
| 63 | attributes: {
|
| 64 | names: string[];
|
| 65 | values: string[];
|
| 66 | };
|
| 67 | classes: string[];
|
| 68 | ids: string[];
|
| 69 | tags: string[];
|
| 70 | undetermined: string[];
|
| 71 | }
|
| 72 |
|
| 73 | /**
|
| 74 | * @public
|
| 75 | */
|
| 76 | export declare class ExtractorResultSets {
|
| 77 | private undetermined;
|
| 78 | private attrNames;
|
| 79 | private attrValues;
|
| 80 | private classes;
|
| 81 | private ids;
|
| 82 | private tags;
|
| 83 | constructor(er: ExtractorResult);
|
| 84 | merge(that: ExtractorResult | ExtractorResultSets): this;
|
| 85 | hasAttrName(name: string): boolean;
|
| 86 | private someAttrValue;
|
| 87 | hasAttrPrefix(prefix: string): boolean;
|
| 88 | hasAttrSuffix(suffix: string): boolean;
|
| 89 | hasAttrSubstr(substr: string): boolean;
|
| 90 | hasAttrValue(value: string): boolean;
|
| 91 | hasClass(name: string): boolean;
|
| 92 | hasId(id: string): boolean;
|
| 93 | hasTag(tag: string): boolean;
|
| 94 | }
|
| 95 |
|
| 96 | /**
|
| 97 | * @public
|
| 98 | */
|
| 99 | export declare interface Extractors {
|
| 100 | extensions: string[];
|
| 101 | extractor: ExtractorFunction;
|
| 102 | }
|
| 103 |
|
| 104 | /* Excluded from this release type: IgnoreType */
|
| 105 |
|
| 106 | /**
|
| 107 | * Merge two extractor selectors
|
| 108 | *
|
| 109 | * @param extractorSelectorsA - extractor selectors A
|
| 110 | * @param extractorSelectorsB - extractor selectors B
|
| 111 | * @returns the merged extractor result sets
|
| 112 | *
|
| 113 | * @public
|
| 114 | */
|
| 115 | export declare function mergeExtractorSelectors(...extractors: (ExtractorResultDetailed | ExtractorResultSets)[]): ExtractorResultSets;
|
| 116 |
|
| 117 | /**
|
| 118 | * Options used by PurgeCSS to remove unused CSS
|
| 119 | * Those options are used internally
|
| 120 | * @see {@link UserDefinedOptions} for the options defined by the user
|
| 121 | *
|
| 122 | * @public
|
| 123 | */
|
| 124 | export declare interface Options {
|
| 125 | /**
|
| 126 | * You can specify content that should be analyzed by PurgeCSS with an
|
| 127 | * array of filenames or globs. The files can be HTML, Pug, Blade, etc.
|
| 128 | *
|
| 129 | * @example
|
| 130 | *
|
| 131 | * ```ts
|
| 132 | * await new PurgeCSS().purge({
|
| 133 | * content: ['index.html', '*.js', '*.html', '*.vue'],
|
| 134 | * css: ['css/app.css']
|
| 135 | * })
|
| 136 | * ```
|
| 137 | *
|
| 138 | * @example
|
| 139 | * PurgeCSS also works with raw content. To do this, you need to pass an
|
| 140 | * object with the `raw` property instead of a filename. To work properly
|
| 141 | * with custom extractors you need to pass the `extension` property along
|
| 142 | * with the raw content.
|
| 143 | *
|
| 144 | * ```ts
|
| 145 | * await new PurgeCSS().purge({
|
| 146 | * content: [
|
| 147 | * {
|
| 148 | * raw: '<html><body><div class="app"></div></body></html>',
|
| 149 | * extension: 'html'
|
| 150 | * },
|
| 151 | * '*.js',
|
| 152 | * '*.html',
|
| 153 | * '*.vue'
|
| 154 | * ],
|
| 155 | * css: [
|
| 156 | * {
|
| 157 | * raw: 'body { margin: 0 }'
|
| 158 | * },
|
| 159 | * 'css/app.css'
|
| 160 | * ]
|
| 161 | * })
|
| 162 | * ```
|
| 163 | */
|
| 164 | content: Array<string | RawContent>;
|
| 165 | /**
|
| 166 | * Similar to content, you can specify css that should be processed by
|
| 167 | * PurgeCSS with an array of filenames or globs
|
| 168 | */
|
| 169 | css: Array<string | RawCSS>;
|
| 170 | defaultExtractor: ExtractorFunction;
|
| 171 | extractors: Array<Extractors>;
|
| 172 | /**
|
| 173 | * If there are any unused \@font-face rules in your css, you can remove
|
| 174 | * them by setting the `fontFace` option to `true`.
|
| 175 | *
|
| 176 | * @defaultValue `false`
|
| 177 | *
|
| 178 | * @example
|
| 179 | * ```ts
|
| 180 | * await new PurgeCSS().purge({
|
| 181 | * content: ['index.html', '*.js', '*.html', '*.vue'],
|
| 182 | * css: ['css/app.css'],
|
| 183 | * fontFace: true
|
| 184 | * })
|
| 185 | * ```
|
| 186 | */
|
| 187 | fontFace: boolean;
|
| 188 | keyframes: boolean;
|
| 189 | output?: string;
|
| 190 | rejected: boolean;
|
| 191 | rejectedCss: boolean;
|
| 192 | /** {@inheritDoc postcss#SourceMapOptions} */
|
| 193 | sourceMap: boolean | (postcss.SourceMapOptions & {
|
| 194 | to?: string;
|
| 195 | });
|
| 196 | stdin: boolean;
|
| 197 | stdout: boolean;
|
| 198 | variables: boolean;
|
| 199 | /**
|
| 200 | * You can indicate which selectors are safe to leave in the final CSS.
|
| 201 | * This can be accomplished with the option safelist.
|
| 202 | */
|
| 203 | safelist: Required<ComplexSafelist>;
|
| 204 | /**
|
| 205 | * Blocklist will block the CSS selectors from appearing in the final
|
| 206 | * output CSS. The selectors will be removed even when they are seen
|
| 207 | * as used by PurgeCSS.
|
| 208 | */
|
| 209 | blocklist: StringRegExpArray;
|
| 210 | /**
|
| 211 | * If you provide globs for the content parameter, you can use this option
|
| 212 | * to exclude certain files or folders that would otherwise be scanned.
|
| 213 | * Pass an array of globs matching items that should be excluded.
|
| 214 | * (Note: this option has no effect if content is not globs.)
|
| 215 | */
|
| 216 | skippedContentGlobs: Array<string>;
|
| 217 | /**
|
| 218 | * Option to add custom CSS attribute selectors like "aria-selected",
|
| 219 | * "data-selected", ...etc.
|
| 220 | */
|
| 221 | dynamicAttributes: string[];
|
| 222 | }
|
| 223 |
|
| 224 | /**
|
| 225 | * @public
|
| 226 | */
|
| 227 | export declare type PostCSSRoot = postcss.Root;
|
| 228 |
|
| 229 | /**
|
| 230 | * Class used to instantiate PurgeCSS and can then be used
|
| 231 | * to purge CSS files.
|
| 232 | *
|
| 233 | * @example
|
| 234 | * ```ts
|
| 235 | * await new PurgeCSS().purge({
|
| 236 | * content: ['index.html'],
|
| 237 | * css: ['css/app.css']
|
| 238 | * })
|
| 239 | * ```
|
| 240 | *
|
| 241 | * @public
|
| 242 | */
|
| 243 | export declare class PurgeCSS {
|
| 244 | private ignore;
|
| 245 | private atRules;
|
| 246 | private usedAnimations;
|
| 247 | private usedFontFaces;
|
| 248 | selectorsRemoved: Set<string>;
|
| 249 | removedNodes: postcss.Node[];
|
| 250 | variablesStructure: VariablesStructure;
|
| 251 | options: Options;
|
| 252 | private collectDeclarationsData;
|
| 253 | /**
|
| 254 | * Get the extractor corresponding to the extension file
|
| 255 | * @param filename - Name of the file
|
| 256 | * @param extractors - Array of extractors definition
|
| 257 | */
|
| 258 | private getFileExtractor;
|
| 259 | /**
|
| 260 | * Extract the selectors present in the files using a PurgeCSS extractor
|
| 261 | *
|
| 262 | * @param files - Array of files path or glob pattern
|
| 263 | * @param extractors - Array of extractors
|
| 264 | */
|
| 265 | extractSelectorsFromFiles(files: string[], extractors: Extractors[]): Promise<ExtractorResultSets>;
|
| 266 | /**
|
| 267 | * Extract the selectors present in the passed string using a PurgeCSS extractor
|
| 268 | *
|
| 269 | * @param content - Array of content
|
| 270 | * @param extractors - Array of extractors
|
| 271 | */
|
| 272 | extractSelectorsFromString(content: RawContent[], extractors: Extractors[]): Promise<ExtractorResultSets>;
|
| 273 | /**
|
| 274 | * Evaluate at-rule and register it for future reference
|
| 275 | * @param node - node of postcss AST
|
| 276 | */
|
| 277 | private evaluateAtRule;
|
| 278 | /**
|
| 279 | * Evaluate css selector and decide if it should be removed or not
|
| 280 | *
|
| 281 | * @param node - node of postcss AST
|
| 282 | * @param selectors - selectors used in content files
|
| 283 | */
|
| 284 | private evaluateRule;
|
| 285 | /**
|
| 286 | * Get the purged version of the css based on the files
|
| 287 | *
|
| 288 | * @param cssOptions - css options, files or raw strings
|
| 289 | * @param selectors - set of extracted css selectors
|
| 290 | */
|
| 291 | getPurgedCSS(cssOptions: Array<string | RawCSS>, selectors: ExtractorResultSets): Promise<ResultPurge[]>;
|
| 292 | /**
|
| 293 | * Check if the keyframe is safelisted with the option safelist keyframes
|
| 294 | *
|
| 295 | * @param keyframesName - name of the keyframe animation
|
| 296 | */
|
| 297 | private isKeyframesSafelisted;
|
| 298 | /**
|
| 299 | * Check if the selector is blocklisted with the option blocklist
|
| 300 | *
|
| 301 | * @param selector - css selector
|
| 302 | */
|
| 303 | private isSelectorBlocklisted;
|
| 304 | /**
|
| 305 | * Check if the selector is safelisted with the option safelist standard
|
| 306 | *
|
| 307 | * @param selector - css selector
|
| 308 | */
|
| 309 | private isSelectorSafelisted;
|
| 310 | /**
|
| 311 | * Check if the selector is safelisted with the option safelist deep
|
| 312 | *
|
| 313 | * @param selector - selector
|
| 314 | */
|
| 315 | private isSelectorSafelistedDeep;
|
| 316 | /**
|
| 317 | * Check if the selector is safelisted with the option safelist greedy
|
| 318 | *
|
| 319 | * @param selector - selector
|
| 320 | */
|
| 321 | private isSelectorSafelistedGreedy;
|
| 322 | /**
|
| 323 | * Remove unused CSS
|
| 324 | *
|
| 325 | * @param userOptions - PurgeCSS options or path to the configuration file
|
| 326 | * @returns an array of object containing the filename and the associated CSS
|
| 327 | *
|
| 328 | * @example Using a configuration file named purgecss.config.js
|
| 329 | * ```ts
|
| 330 | * const purgeCSSResults = await new PurgeCSS().purge()
|
| 331 | * ```
|
| 332 | *
|
| 333 | * @example Using a custom path to the configuration file
|
| 334 | * ```ts
|
| 335 | * const purgeCSSResults = await new PurgeCSS().purge('./purgecss.config.js')
|
| 336 | * ```
|
| 337 | *
|
| 338 | * @example Using the PurgeCSS options
|
| 339 | * ```ts
|
| 340 | * const purgeCSSResults = await new PurgeCSS().purge({
|
| 341 | * content: ['index.html', '**\/*.js', '**\/*.html', '**\/*.vue'],
|
| 342 | * css: ['css/app.css']
|
| 343 | * })
|
| 344 | * ```
|
| 345 | */
|
| 346 | purge(userOptions: UserDefinedOptions | string | undefined): Promise<ResultPurge[]>;
|
| 347 | /**
|
| 348 | * Remove unused CSS variables
|
| 349 | */
|
| 350 | removeUnusedCSSVariables(): void;
|
| 351 | /**
|
| 352 | * Remove unused font-faces
|
| 353 | */
|
| 354 | removeUnusedFontFaces(): void;
|
| 355 | /**
|
| 356 | * Remove unused keyframes
|
| 357 | */
|
| 358 | removeUnusedKeyframes(): void;
|
| 359 | /**
|
| 360 | * Transform a selector node into a string
|
| 361 | */
|
| 362 | private getSelectorValue;
|
| 363 | /**
|
| 364 | * Determine if the selector should be kept, based on the selectors found in the files
|
| 365 | *
|
| 366 | * @param selector - set of css selectors found in the content files or string
|
| 367 | * @param selectorsFromExtractor - selectors in the css rule
|
| 368 | *
|
| 369 | * @returns true if the selector should be kept in the processed CSS
|
| 370 | */
|
| 371 | private shouldKeepSelector;
|
| 372 | /**
|
| 373 | * Walk through the CSS AST and remove unused CSS
|
| 374 | *
|
| 375 | * @param root - root node of the postcss AST
|
| 376 | * @param selectors - selectors used in content files
|
| 377 | */
|
| 378 | walkThroughCSS(root: PostCSSRoot, selectors: ExtractorResultSets): void;
|
| 379 | }
|
| 380 |
|
| 381 | /**
|
| 382 | * @public
|
| 383 | */
|
| 384 | export declare interface RawContent<T = string> {
|
| 385 | extension: string;
|
| 386 | raw: T;
|
| 387 | }
|
| 388 |
|
| 389 | /**
|
| 390 | * @public
|
| 391 | */
|
| 392 | export declare interface RawCSS {
|
| 393 | raw: string;
|
| 394 | name?: string;
|
| 395 | }
|
| 396 |
|
| 397 | /**
|
| 398 | * @public
|
| 399 | */
|
| 400 | export declare interface ResultPurge {
|
| 401 | css: string;
|
| 402 | /**
|
| 403 | * sourceMap property will be empty if
|
| 404 | * {@link UserDefinedOptions.sourceMap} inline is not set to false, as the
|
| 405 | * source map will be contained within the text of ResultPurge.css
|
| 406 | */
|
| 407 | sourceMap?: string;
|
| 408 | rejectedCss?: string;
|
| 409 | file?: string;
|
| 410 | rejected?: string[];
|
| 411 | }
|
| 412 |
|
| 413 | /**
|
| 414 | * Load the configuration file from the path
|
| 415 | *
|
| 416 | * @param configFile - Path of the config file
|
| 417 | * @returns The options from the configuration file
|
| 418 | *
|
| 419 | * @throws Error
|
| 420 | * This exception is thrown if the configuration file was not imported
|
| 421 | *
|
| 422 | * @public
|
| 423 | */
|
| 424 | export declare function setOptions(configFile?: string): Promise<Options>;
|
| 425 |
|
| 426 | /**
|
| 427 | * Format the user defined safelist into a standardized safelist object
|
| 428 | *
|
| 429 | * @param userDefinedSafelist - the user defined safelist
|
| 430 | * @returns the formatted safelist object that can be used in the PurgeCSS options
|
| 431 | *
|
| 432 | * @public
|
| 433 | */
|
| 434 | export declare function standardizeSafelist(userDefinedSafelist?: UserDefinedSafelist): Required<ComplexSafelist>;
|
| 435 |
|
| 436 | /**
|
| 437 | * @public
|
| 438 | */
|
| 439 | export declare type StringRegExpArray = Array<RegExp | string>;
|
| 440 |
|
| 441 | /**
|
| 442 | * Options used by PurgeCSS to remove unused CSS
|
| 443 | *
|
| 444 | * @public
|
| 445 | */
|
| 446 | export declare interface UserDefinedOptions {
|
| 447 | /** {@inheritDoc purgecss#Options.content} */
|
| 448 | content: Array<string | RawContent>;
|
| 449 | /** {@inheritDoc purgecss#Options.css} */
|
| 450 | css: Array<string | RawCSS>;
|
| 451 | /** {@inheritDoc purgecss#Options.defaultExtractor} */
|
| 452 | defaultExtractor?: ExtractorFunction;
|
| 453 | /** {@inheritDoc purgecss#Options.extractors} */
|
| 454 | extractors?: Array<Extractors>;
|
| 455 | /** {@inheritDoc purgecss#Options.fontFace} */
|
| 456 | fontFace?: boolean;
|
| 457 | /** {@inheritDoc purgecss#Options.keyframes} */
|
| 458 | keyframes?: boolean;
|
| 459 | /** {@inheritDoc purgecss#Options.output} */
|
| 460 | output?: string;
|
| 461 | /** {@inheritDoc purgecss#Options.rejected} */
|
| 462 | rejected?: boolean;
|
| 463 | /** {@inheritDoc purgecss#Options.rejectedCss} */
|
| 464 | rejectedCss?: boolean;
|
| 465 | /** {@inheritDoc purgecss#Options.sourceMap } */
|
| 466 | sourceMap?: boolean | (postcss.SourceMapOptions & {
|
| 467 | to?: string;
|
| 468 | });
|
| 469 | /** {@inheritDoc purgecss#Options.stdin} */
|
| 470 | stdin?: boolean;
|
| 471 | /** {@inheritDoc purgecss#Options.stdout} */
|
| 472 | stdout?: boolean;
|
| 473 | /** {@inheritDoc purgecss#Options.variables} */
|
| 474 | variables?: boolean;
|
| 475 | /** {@inheritDoc purgecss#Options.safelist} */
|
| 476 | safelist?: UserDefinedSafelist;
|
| 477 | /** {@inheritDoc purgecss#Options.blocklist} */
|
| 478 | blocklist?: StringRegExpArray;
|
| 479 | /** {@inheritDoc purgecss#Options.skippedContentGlobs} */
|
| 480 | skippedContentGlobs?: Array<string>;
|
| 481 | /** {@inheritDoc purgecss#Options.dynamicAttributes} */
|
| 482 | dynamicAttributes?: string[];
|
| 483 | }
|
| 484 |
|
| 485 | /**
|
| 486 | * @public
|
| 487 | */
|
| 488 | export declare type UserDefinedSafelist = StringRegExpArray | ComplexSafelist;
|
| 489 |
|
| 490 | /**
|
| 491 | * @public
|
| 492 | */
|
| 493 | export declare class VariableNode {
|
| 494 | nodes: VariableNode[];
|
| 495 | value: postcss.Declaration;
|
| 496 | isUsed: boolean;
|
| 497 | constructor(declaration: postcss.Declaration);
|
| 498 | }
|
| 499 |
|
| 500 | /**
|
| 501 | * @public
|
| 502 | */
|
| 503 | export declare class VariablesStructure {
|
| 504 | nodes: Map<string, VariableNode[]>;
|
| 505 | usedVariables: Set<string>;
|
| 506 | safelist: StringRegExpArray;
|
| 507 | addVariable(declaration: postcss.Declaration): void;
|
| 508 | addVariableUsage(declaration: postcss.Declaration, matchedVariables: IterableIterator<RegExpMatchArray>): void;
|
| 509 | addVariableUsageInProperties(matchedVariables: IterableIterator<RegExpMatchArray>): void;
|
| 510 | setAsUsed(variableName: string): void;
|
| 511 | removeUnused(): void;
|
| 512 | isVariablesSafelisted(variable: string): boolean;
|
| 513 | }
|
| 514 |
|
| 515 | export { }
|