or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdcontent-extraction.mdcore-purging.mdcss-variables.mdindex.mdsafelist-configuration.md
tile.json

tessl/npm-purgecss

Remove unused css selectors

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/purgecss@7.0.x

To install, run

npx @tessl/cli install tessl/npm-purgecss@7.0.0

index.mddocs/

PurgeCSS

PurgeCSS is a comprehensive CSS optimization library and command-line tool that analyzes content files (HTML, JavaScript, etc.) and CSS files to identify and remove unused CSS selectors, significantly reducing bundle sizes. It features a powerful selector matching engine using PostCSS, customizable extractors for different file types, safelist functionality to protect specific selectors from removal, and extensive integration options through plugins for popular build tools.

Package Information

  • Package Name: purgecss
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install purgecss

Core Imports

import { 
  PurgeCSS, 
  defaultOptions, 
  standardizeSafelist,
  setOptions,
  mergeExtractorSelectors,
  ExtractorResultSets,
  VariablesStructure,
  VariableNode
} from "purgecss";

For CommonJS:

const { 
  PurgeCSS, 
  defaultOptions, 
  standardizeSafelist,
  setOptions,
  mergeExtractorSelectors,
  ExtractorResultSets,
  VariablesStructure,
  VariableNode
} = require("purgecss");

Basic Usage

import { PurgeCSS } from "purgecss";

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

console.log(purgeCSSResults[0].css); // Purged CSS

// Advanced usage with safelist
const results = await new PurgeCSS().purge({
  content: ['src/**/*.html', 'src/**/*.js'],
  css: ['styles/*.css'],
  safelist: ['btn', 'btn-primary', /^modal-/],
  variables: true,
  keyframes: true,
  fontFace: true
});

Architecture

PurgeCSS is built around several key components:

  • PurgeCSS Class: Main API providing purge operations and selector extraction
  • Content Extractors: Pluggable system for extracting selectors from different file types (HTML, Pug, JSX, etc.)
  • PostCSS Integration: Uses PostCSS for CSS parsing and manipulation with selector parsing via postcss-selector-parser
  • Selector Matching Engine: Advanced matching logic supporting complex CSS selectors, pseudo-classes, and attribute selectors
  • Safelist System: Flexible safelist patterns (standard, deep, greedy) for protecting selectors from removal
  • Variables Tracking: CSS custom properties dependency analysis and unused variable removal
  • CLI Interface: Complete command-line tool with all programmatic options available

Capabilities

Core CSS Purging

Main PurgeCSS class providing comprehensive CSS optimization functionality with selector extraction, matching, and removal operations.

class PurgeCSS {
  purge(userOptions?: UserDefinedOptions | string): Promise<ResultPurge[]>;
  extractSelectorsFromFiles(files: string[], extractors: Extractors[]): Promise<ExtractorResultSets>;
  extractSelectorsFromString(content: RawContent[], extractors: Extractors[]): Promise<ExtractorResultSets>;
}

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

interface ResultPurge {
  css: string;
  sourceMap?: string;
  rejectedCss?: string;
  file?: string;
  rejected?: string[];
}

Core Purging API

Content Extraction System

Flexible extractor system for analyzing different file types and extracting CSS selectors from content files.

type ExtractorFunction<T = string> = (content: T) => ExtractorResult;

type ExtractorResult = ExtractorResultDetailed | string[];

interface ExtractorResultDetailed {
  attributes: {
    names: string[];
    values: string[];
  };
  classes: string[];
  ids: string[];
  tags: string[];
  undetermined: string[];
}

interface Extractors {
  extensions: string[];
  extractor: ExtractorFunction;
}

class ExtractorResultSets {
  constructor(er: ExtractorResult);
  merge(that: ExtractorResult | ExtractorResultSets): this;
  hasClass(name: string): boolean;
  hasId(id: string): boolean; 
  hasTag(tag: string): boolean;
  hasAttrName(name: string): boolean;
  hasAttrValue(value: string): boolean;
}

Content Extraction

Safelist and Filtering

Advanced safelist system with multiple patterns for protecting selectors from removal, plus blocklist functionality.

type UserDefinedSafelist = StringRegExpArray | ComplexSafelist;

interface ComplexSafelist {
  standard?: StringRegExpArray;
  deep?: RegExp[];
  greedy?: RegExp[];
  variables?: StringRegExpArray;
  keyframes?: StringRegExpArray;
}

type StringRegExpArray = Array<RegExp | string>;

function standardizeSafelist(userDefinedSafelist?: UserDefinedSafelist): Required<ComplexSafelist>;

Safelist Configuration

CSS Variables Management

CSS custom properties (variables) dependency tracking and unused variable removal functionality.

class VariablesStructure {
  nodes: Map<string, VariableNode[]>;
  usedVariables: Set<string>;
  safelist: StringRegExpArray;
  
  addVariable(declaration: postcss.Declaration): void;
  addVariableUsage(declaration: postcss.Declaration, matchedVariables: IterableIterator<RegExpMatchArray>): void;
  removeUnused(): void;
  isVariablesSafelisted(variable: string): boolean;
}

class VariableNode {
  nodes: VariableNode[];
  value: postcss.Declaration;
  isUsed: boolean;
  
  constructor(declaration: postcss.Declaration);
}

CSS Variables

Configuration and Utilities

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

const defaultOptions: Options;

function setOptions(configFile?: string): Promise<Options>;
function standardizeSafelist(userDefinedSafelist?: UserDefinedSafelist): Required<ComplexSafelist>;
function mergeExtractorSelectors(...extractors: (ExtractorResultDetailed | ExtractorResultSets)[]): ExtractorResultSets;

Configuration

Content Types

interface RawContent<T = string> {
  extension: string;
  raw: T;
}

interface RawCSS {
  raw: string;
  name?: string;
}

PostCSS Integration

type PostCSSRoot = postcss.Root;