PurgeCSSPurgeCSS
API Reference
  • English
  • Français
GitHub
API Reference
  • English
  • Français
GitHub
  • PurgeCSS

    • About PurgeCSS
    • Getting Started
    • Configuration
    • Command Line Interface
    • Programmatic API
    • Safelisting
    • Extractors
  • Plugins

    • PostCSS
    • Webpack
    • Rollup
    • Gulp
    • Grunt
    • Gatsby
  • Guides

    • Vue
    • React
    • Angular
    • Next.js
    • Nuxt.js
    • Razzle
    • WordPress
    • Hugo
  • Comparison
  • Common Questions

    • How to use with CSS modules
    • How to use with Ant Design

Programmatic API

Start by installing PurgeCSS as a dev dependency.

:::: code-group ::: code-group-item NPM

npm install purgecss --save-dev

::: ::: code-group-item YARN

yarn add purgecss --dev

::: ::::

You can now use PurgeCSS inside a JavaScript file.

In the following examples, the options passed to PurgeCSS are the same as the ones here. The result purgecssResult is an array of an object containing the name of the files with the purged CSS.

Usage

ES Module Import Syntax

import { PurgeCSS } from 'purgecss'
const purgeCSSResult = await new PurgeCSS().purge({
  content: ['**/*.html'],
  css: ['**/*.css']
})

CommonJS Syntax

const { PurgeCSS } = require('purgecss')
const purgeCSSResult = await new PurgeCSS().purge({
  content: ['**/*.html'],
  css: ['**/*.css']
})

The format of purgeCSSResult is

[
    {
        file: 'main.css',
        css: '/* purged css for main.css */'
    },
    {
        file: 'animate.css',
        css: '/* purged css for animate.css */'
    }
]

The type of the result is

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

rejected and rejectedCss are set when the options of the same name are enabled. sourceMap is set when the sourceMap option generates a source map that isn't inlined in the CSS, for example with inline: false.

Reusing extracted content across runs

Integrations that run PurgeCSS many times with the same content, such as a PostCSS plugin called once per CSS file or a bundler plugin in watch mode, can share a ContentCache between their PurgeCSS instances. A content file is then only read and extracted again when its modification time, change time, size, inode or extractor changed. Runs at the same time share the files being read and extracted, so each file is extracted once.

import { ContentCache, PurgeCSS } from 'purgecss'

const contentCache = new ContentCache()

async function purge(css) {
  const purgeCSS = new PurgeCSS()
  purgeCSS.contentCache = contentCache
  return purgeCSS.purge({ content: ['src/**/*.html'], css: [css] })
}

Globs are still resolved on every run, so new files are picked up and deleted files no longer contribute selectors. A file modified or changed less than 2 seconds before it was read (for example written, or given an older modification time by touch -r, cp -p or a backup restore) is extracted again on the next run, as a change within the precision of the file system timestamps could go unnoticed.

The cache keeps an entry for every file it has seen. Call contentCache.prune(paths) to keep only the given files, for example the files the content globs match after a rebuild, or contentCache.delete(path) and contentCache.clear(). The paths given to prune, delete and has are resolved from the current working directory, and contentCache.keys() lists the absolute paths of the files in the cache.

Content files are read and extracted in parallel, with or without a cache, at most 32 at a time for all the runs of the process together, so extractors can be called at the same time and in any order. An extractor must only depend on the content it is given, not on the files it saw before.

Edit this page
Last Updated: 11/20/26, 3:02 AM
Prev
Command Line Interface
Next
Safelisting