To help you get started, we've collected the most common ways that uncss is being used within popular public projects.

mikelambert / dancedeets-monorepo / server / uncssWebpackGenerator.js View on Github

// This handles a bunch for us:
                    // autoprefixer: Adds vendor prefixes to CSS, using Autoprefixer.
                    // filters: Converts CSS shorthand filters to SVG equivalent
                    // rem: Generates pixel fallbacks for rem units
                    // pseudoElements: Converts pseudo-elements using CSS3 syntax
                    //   (two-colons notation like ::after, ::before, ::first-line and ::first-letter) with the old one
                    // opacity: Adds opacity filter for IE8 when using opacity property
                    //
                    // We intentionally don't do any minification, since we'd prefer to run uncss first
                    pleeease({
                      import: false,
                      rebaseUrls: false,
                      minifier: false,
                      browsers: ['> 2%'],
                    }),
                    uncss.postcssPlugin({
                      html: [...htmlFiles, 'amp/empty.html'],
                      ignore,
                    }),
                  ],
                },

View more ways to use uncss

UnCSS

UnCSS is a tool that removes unused CSS from your stylesheets. It works across multiple files and supports Javascript-injected CSS.

How

The process by which UnCSS removes the unused rules is as follows:

1. The HTML files are loaded by jsdom and JavaScript is executed.
2. All the stylesheets are parsed by PostCSS.
3. document.querySelector filters out selectors that are not found in the HTML files.
4. The remaining rules are converted back to CSS.

Please note:

• UnCSS cannot be run on non-HTML pages, such as templates or PHP files. If you need to run UnCSS against your templates, you should probably generate example HTML pages from your templates, and run uncss on those generated files; or run a live local dev server, and point uncss at that.
• UnCSS only runs the Javascript that is run on page load. It does not (and cannot) handle Javascript that runs on user interactions like button clicks. You must use the ignore option to preserve classes that are added by Javascript on user interaction.

Installation

npm install -g uncss

Usage

Online Server

• https://uncss-online.com/ - Unofficial server, very convenient for testing or one-off usage!

Within Node.js

var uncss = require('uncss');

var files   = ['my', 'array', 'of', 'HTML', 'files', 'or', 'https://urls.com'],
    options = {
        banner       : false,
        csspath      : '../public/css/',
        htmlroot     : 'public',
        ignore       : ['#added_at_runtime', /test\-[0-9]+/],
        ignoreSheets : [/fonts.googleapis/],
        inject       : function(window) { window.document.querySelector('html').classList.add('no-csscalc', 'csscalc'); },
        jsdom        : {
            userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 10_3 like Mac OS X)',
        },
        media        : ['(min-width: 700px) handheld and (orientation: landscape)'],
        raw          : 'h1 { color: green }',
        report       : false,
        strictSSL    : true,
        stylesheets  : ['lib/bootstrap/dist/css/bootstrap.css', 'src/public/css/main.css'],
        timeout      : 1000,
        uncssrc      : '.uncssrc',
        userAgent    : 'Mozilla/5.0 (iPhone; CPU iPhone OS 10_3 like Mac OS X)',
    };

uncss(files, options, function (error, output) {
    console.log(output);
});

/* Look Ma, no options! */
uncss(files, function (error, output) {
    console.log(output);
});

/* Specifying raw HTML */
var rawHtml = '...';

uncss(rawHtml, options, function (error, output) {
    console.log(output);
});

At build-time

UnCSS can also be used in conjunction with other JavaScript build systems, such as Grunt, Broccoli or Gulp!

• grunt-uncss – Thanks to @addyosmani
• gulp-uncss – Thanks to @ben-eb
• broccoli-uncss - Thanks to @sindresorhus

From the command line

Usage: uncss [options] 
    e.g. uncss https://getbootstrap.com/docs/3.3/examples/jumbotron/ > stylesheet.css

Options:

  -h, --help                            output usage information
  -V, --version                         output the version number
  -i, --ignore           Do not remove given selectors
  -m, --media         Process additional media queries
  -C, --csspath