Purify-CSS vs UnCSS: Technical Comparison for Legacy and Modern Stacks

Both purify-css and uncss solve the same critical problem: removing unused CSS to shrink bundle sizes and improve load times. However, they take fundamentally different approaches to detecting what is "unused," leading to distinct trade-offs in accuracy, performance, and maintenance. Understanding these differences is vital when dealing with legacy systems or deciding whether to migrate to modern alternatives.

🔍 Detection Strategy: Static Parsing vs. Headless Rendering

The core difference lies in how each tool decides which CSS rules to keep.

purify-css uses static analysis. It reads your source files (HTML, JS, templates) as text, extracts strings that look like class names or IDs using regular expressions, and compares them against your CSS selectors.

// purify-css: Static analysis configuration
const purify = require('purify-css');

purify(['src/**/*.html', 'src/**/*.js'], ['src/**/*.css'], {
  output: 'dist/clean.css',
  // It simply looks for strings matching class patterns
  minify: true
});

uncss uses dynamic rendering. It spins up a headless browser (historically PhantomJS) to actually load your pages, execute JavaScript, and render the DOM. It then snapshots the computed styles to see what is truly being used.

// uncss: Dynamic rendering configuration
const uncss = require('uncss');

uncss(['http://localhost:8080/index.html'], {
  css: ['src/styles.css'],
  // It loads the URL in a browser to find used styles
  ignore: ['.js-added-class'] 
}, function(error, output) {
  console.log(output);
});

⚡ Performance and Dependencies

Because of their detection strategies, the runtime requirements differ significantly.

purify-css is extremely fast and lightweight. It runs purely in Node.js with no external binaries. You can run it on any CI/CD server without extra setup.

# purify-css: Runs instantly in any Node environment
npm install purify-css
# No additional system dependencies required

uncss is heavy and slow. It requires a headless browser engine. Historically, it depended on PhantomJS, which is now obsolete. Running it often requires installing system-level libraries for browser rendering, making CI/CD setup cumbersome.

# uncss: Requires heavy system dependencies
npm install uncss
# Historically required PhantomJS installation on the OS
# This often fails on modern minimal Docker images or CI runners

🎯 Accuracy with Dynamic Content

Static analysis often struggles with dynamic classes, while rendering engines handle them naturally.

purify-css can miss classes added by JavaScript at runtime if they aren't present as strings in the source code. You often need to manually whitelist these patterns.

// purify-css: May miss dynamic classes unless whitelisted
purify(files, css, {
  output: 'clean.css',
  // Must manually tell it to keep classes matching this pattern
  whitelist: ['.is-active', '/^js-/' ] 
});

uncss naturally catches dynamic classes because it executes the JavaScript on the page. If a script adds a class after load, uncss sees it in the DOM and keeps the CSS.

// uncss: Automatically detects runtime classes
// No whitelist needed for classes added by JS execution
uncss(urls, options, function(err, output) {
  // The output includes styles for classes added via DOM manipulation
});

🛑 Maintenance Status and Deprecation Warning

This is the most critical factor for architectural decisions today.

purify-css is no longer actively maintained. The original repository has seen little activity in recent years. While it still works for many setups, it lacks support for modern CSS features and newer framework patterns. Developers are strongly encouraged to migrate to purgecss, which is the spiritual successor with active maintenance and a plugin ecosystem.

// purify-css: Deprecated/Inactive
// Recommendation: Migrate to 'purgecss'
// const purgecss = require('purgecss'); // Active alternative

uncss is officially deprecated. The project is archived, and its dependency on PhantomJS (which is also dead) makes it incompatible with modern security standards and build environments. It should not be used in any new project.

// uncss: Deprecated and Archived
// DO NOT USE in new projects.
// The underlying PhantomJS engine is insecure and obsolete.
// Modern alternative: Use PurgeCSS with a custom extractor or critical CSS tools.

🏗️ Integration with Build Tools

Both tools offered plugins for popular loaders, but support varies.

purify-css had simple webpack plugins but required manual configuration for many frameworks.

// purify-css: Webpack plugin example (Legacy)
const PurifyCSSPlugin = require('purify-css-webpack');

module.exports = {
  plugins: [
    new PurifyCSSPlugin({
      paths: glob.sync(path.join(__dirname, 'app/*.js'))
    })
  ]
};

uncss integrated deeply with task runners like Gulp, often as part of a larger pipeline involving server spinning.

// uncss: Gulp task example (Legacy)
const gulp = require('gulp');
const uncss = require('gulp-uncss');

gulp.task('css', function () {
  return gulp.src('src/**/*.css')
    .pipe(uncss({
      html: ['http://localhost:3000']
    }))
    .pipe(gulp.dest('dist'));
});

📊 Summary: Key Differences

💡 The Big Picture

purify-css was a reliable workhorse for simple, static projects where build speed mattered more than 100% accuracy. However, its lack of maintenance makes it a risk for modern stacks. If you are currently using it, plan a migration to purgecss, which offers the same static analysis benefits with active support and better framework integration.

uncss was a powerful tool for complex applications where JavaScript heavily manipulated the DOM. Its ability to "see" the rendered page was unique. However, the death of PhantomJS and the project itself means it is now a liability. Using it today introduces security vulnerabilities and build instability.

Final Recommendation: Do not start new projects with either of these packages. The industry has standardized around purgecss. It combines the speed of static analysis with the ability to write custom extractors for dynamic frameworks (like React, Vue, and Angular), effectively replacing the need for heavy headless browsers while maintaining high accuracy. Use purify-css or uncss only when maintaining older legacy builds that cannot yet be refactored.