Core CSS Purging

/**
 * Class used to instantiate PurgeCSS and can then be used to purge CSS files.
 */
class PurgeCSS {
  options: Options;
  selectorsRemoved: Set<string>;
  removedNodes: postcss.Node[];
  variablesStructure: VariablesStructure;
}

/**
 * Remove unused CSS
 * @param userOptions - PurgeCSS options or path to the configuration file
 * @returns Promise resolving to array of purged CSS results
 */
purge(userOptions?: UserDefinedOptions | string): Promise<ResultPurge[]>;

import { PurgeCSS } from "purgecss";

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

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

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

/**
 * Extract the selectors present in the files using a PurgeCSS extractor
 * @param files - Array of files path or glob pattern
 * @param extractors - Array of extractors
 * @returns Promise resolving to extracted selector sets
 */
extractSelectorsFromFiles(files: string[], extractors: Extractors[]): Promise<ExtractorResultSets>;

/**
 * Extract the selectors present in the passed string using a PurgeCSS extractor
 * @param content - Array of content with raw strings and extensions
 * @param extractors - Array of extractors
 * @returns Promise resolving to extracted selector sets
 */
extractSelectorsFromString(content: RawContent[], extractors: Extractors[]): Promise<ExtractorResultSets>;

/**
 * Get the purged version of the css based on the files
 * @param cssOptions - css options, files or raw strings
 * @param selectors - set of extracted css selectors
 * @returns Promise resolving to array of purged CSS results
 */
getPurgedCSS(cssOptions: Array<string | RawCSS>, selectors: ExtractorResultSets): Promise<ResultPurge[]>;

/**
 * Walk through the CSS AST and remove unused CSS
 * @param root - root node of the postcss AST
 * @param selectors - selectors used in content files
 */
walkThroughCSS(root: PostCSSRoot, selectors: ExtractorResultSets): void;

/**
 * Remove unused CSS variables
 */
removeUnusedCSSVariables(): void;

/**
 * Remove unused font-faces
 */
removeUnusedFontFaces(): void;

/**
 * Remove unused keyframes
 */
removeUnusedKeyframes(): void;

interface UserDefinedOptions {
  /** Array of content files/globs or raw content objects to analyze */
  content: Array<string | RawContent>;
  /** Array of CSS files/globs or raw CSS objects to purge */
  css: Array<string | RawCSS>;
  /** Default extractor function for content without specific extractor */
  defaultExtractor?: ExtractorFunction;
  /** Custom extractors for specific file types */
  extractors?: Array<Extractors>;
  /** Enable unused @font-face removal */
  fontFace?: boolean;
  /** Enable unused @keyframes removal */
  keyframes?: boolean;
  /** Output directory for purged CSS files */
  output?: string;
  /** Include rejected selectors in results */
  rejected?: boolean;
  /** Include rejected CSS content in results */
  rejectedCss?: boolean;
  /** Source map generation options */
  sourceMap?: boolean | (postcss.SourceMapOptions & { to?: string });
  /** Read CSS from stdin */
  stdin?: boolean;
  /** Output CSS to stdout */
  stdout?: boolean;
  /** Enable unused CSS variables removal */
  variables?: boolean;
  /** Safelist configuration for protected selectors */
  safelist?: UserDefinedSafelist;
  /** Blocklist configuration for forced removal */
  blocklist?: StringRegExpArray;
  /** Glob patterns to skip during content scanning */
  skippedContentGlobs?: Array<string>;
  /** Custom CSS attribute selectors to preserve */
  dynamicAttributes?: string[];
}

interface Options {
  content: Array<string | RawContent>;
  css: Array<string | RawCSS>;
  defaultExtractor: ExtractorFunction;
  extractors: Array<Extractors>;
  fontFace: boolean;
  keyframes: boolean;
  output?: string;
  rejected: boolean;
  rejectedCss: boolean;
  sourceMap: boolean | (postcss.SourceMapOptions & { to?: string });
  stdin: boolean;
  stdout: boolean;
  variables: boolean;
  safelist: Required<ComplexSafelist>;
  blocklist: StringRegExpArray;
  skippedContentGlobs: Array<string>;
  dynamicAttributes: string[];
}

interface ResultPurge {
  /** Purged CSS content */
  css: string;
  /** Source map (empty if sourceMap inline option not set to false) */
  sourceMap?: string;
  /** Rejected CSS content (if rejectedCss option enabled) */
  rejectedCss?: string;
  /** Original file path (for file-based CSS) */
  file?: string;
  /** Array of rejected selectors (if rejected option enabled) */
  rejected?: string[];
}

interface RawContent<T = string> {
  /** File extension for content type detection */
  extension: string;
  /** Raw content string */
  raw: T;
}

interface RawCSS {
  /** Raw CSS content string */
  raw: string;
  /** Optional name for the CSS content */
  name?: string;
}

type PostCSSRoot = postcss.Root;