tessl/npm-purgecss

Remove unused css selectors

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Safelist Configuration

Name: tessl/npm-purgecss
Author: tessl

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

Capabilities

Safelist Types

Union type representing user-defined safelist configurations.

type UserDefinedSafelist = StringRegExpArray | ComplexSafelist;

type StringRegExpArray = Array<RegExp | string>;

Complex Safelist Interface

Comprehensive safelist configuration with multiple protection strategies.

interface ComplexSafelist {
  /** Standard safelist - exact matches and RegExp patterns for selectors */
  standard?: StringRegExpArray;
  /** Deep safelist - protect selectors and all their children */
  deep?: RegExp[];
  /** Greedy safelist - protect any selector part matching these patterns */
  greedy?: RegExp[];
  /** Variables safelist - protect CSS custom properties */
  variables?: StringRegExpArray;
  /** Keyframes safelist - protect @keyframes animations */
  keyframes?: StringRegExpArray;
}

Safelist Standardization

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

/**
 * Format the user defined safelist into a standardized safelist object
 * @param userDefinedSafelist - User defined safelist configuration
 * @returns Formatted safelist object with all properties defined
 */
function standardizeSafelist(
  userDefinedSafelist?: UserDefinedSafelist
): Required<ComplexSafelist>;

Safelist Patterns

Standard Safelist

Protects selectors that match exactly or via RegExp patterns.

Usage Examples:

import { PurgeCSS } from "purgecss";

// String array format
const results = await new PurgeCSS().purge({
  content: ['index.html'],
  css: ['styles.css'],
  safelist: ['btn', 'btn-primary', 'navbar']
});

// Complex object format with standard patterns
const results2 = await new PurgeCSS().purge({
  content: ['index.html'],
  css: ['styles.css'],
  safelist: {
    standard: ['btn', /^btn-/, /modal$/]
  }
});

Deep Safelist

Protects selectors and all their descendant selectors based on RegExp patterns.

interface ComplexSafelist {
  /**
   * You can safelist selectors and their children based on a regular
   * expression with `safelist.deep`
   * 
   * In this example, selectors such as `.bg-red .child-of-bg` will be left
   * in the final CSS, even if `child-of-bg` is not found.
   */
  deep?: RegExp[];
}

Usage Example:

const results = await new PurgeCSS().purge({
  content: [],
  css: ['styles.css'],
  safelist: {
    deep: [/red$/]  // Protects .bg-red and all its children like .bg-red .child-of-bg
  }
});

Greedy Safelist

Protects any selector if any part of it matches the RegExp patterns.

Usage Example:

const results = await new PurgeCSS().purge({
  content: ['index.html'],
  css: ['styles.css'],
  safelist: {
    greedy: [/^data-/, /^js-/]  // Protects any selector containing data- or js- attributes
  }
});

Variables Safelist

Protects CSS custom properties (variables) from removal.

Usage Example:

const results = await new PurgeCSS().purge({
  content: ['index.html'],
  css: ['styles.css'],
  variables: true,
  safelist: {
    variables: ['--primary-color', /^--theme-/]
  }
});

Keyframes Safelist

Protects @keyframes animations from removal.

Usage Example:

const results = await new PurgeCSS().purge({
  content: ['index.html'],
  css: ['styles.css'],
  keyframes: true,
  safelist: {
    keyframes: ['fadeIn', /^slide/]
  }
});

Blocklist Configuration

Blocklist functionality for forcing removal of specific selectors even if they are found in content.

type StringRegExpArray = Array<RegExp | string>;

Usage Example:

const results = await new PurgeCSS().purge({
  content: ['index.html'],
  css: ['styles.css'],
  blocklist: ['debug', 'temp', /^test-/]  // Force remove these selectors
});

Advanced Safelist Patterns

Combining Multiple Safelist Types

const results = await new PurgeCSS().purge({
  content: ['src/**/*.html', 'src/**/*.js'],
  css: ['styles/*.css'],
  variables: true,
  keyframes: true,
  fontFace: true,
  safelist: {
    standard: ['btn', 'navbar', /^alert-/],
    deep: [/^theme-/, /^layout-/],
    greedy: [/^data-/, /^js-hook/],
    variables: ['--primary', '--secondary', /^--color-/],
    keyframes: ['fadeIn', 'slideOut', /^bounce/]
  },
  blocklist: [/^debug-/, 'temp-class']
});

Dynamic Attributes Protection

PurgeCSS automatically protects certain dynamic HTML attributes that can change based on user interaction.

interface UserDefinedOptions {
  /** Custom CSS attribute selectors to preserve */
  dynamicAttributes?: string[];
}

Built-in protected attributes:

value - Form input values
checked - Checkbox/radio states
selected - Select option states
open - Details/summary states

Usage Example:

const results = await new PurgeCSS().purge({
  content: ['index.html'],
  css: ['styles.css'],
  dynamicAttributes: ['aria-expanded', 'data-active', 'data-state']
});

Internal Safelist

PurgeCSS includes an internal safelist of selectors that are always preserved:

const CSS_SAFELIST = ["*", ":root", ":after", ":before"];

These selectors are fundamental to CSS functionality and are automatically protected regardless of user configuration.

Install with Tessl CLI

npx tessl i tessl/npm-purgecss

docs

configuration.md

content-extraction.md

core-purging.md

css-variables.md

index.md

safelist-configuration.md

tile.json

tessl/npm-purgecss