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

shell
npm install -g uncss

Usage

Online Server

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

Within Node.js

js
var uncss = require('uncss');

var files = ['my', 'array', 'of', 'HTML', 'files', 'or', 'http://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

txt
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                   Relative path where the CSS files are located
  -s, --stylesheets          Specify additional stylesheets to process
  -S, --ignoreSheets     Do not include specified stylesheets
  -r, --raw                     Pass in a raw string of CSS
  -t, --timeout           Wait for JS evaluation
  -H, --htmlroot                Absolute paths' root location
  -u, --uncssrc                   Load these options from 
  -n, --noBanner                        Disable banner
  -a, --userAgent               Use a custom user agent string
  -I, --inject                    Path to javascript file to be executed before uncss runs
  -o, --output                    Path to write resulting CSS to

Note that you can pass both local file paths (which are processed by glob) and URLs to the program.

• banner (boolean, default: true): Whether a banner should be prepended before each file block in the processed CSS.

• csspath (string): Path where the CSS files are related to the HTML files. By default, UnCSS uses the path specified in the `.

• htmlroot (string): Where the project root is. Useful for example if you have HTML that references _local_ files with root-relative URLs, i.e. href="/css/style.css".

css
    /* uncss:ignore */
    .selector1 {
        /* this rule will be ignored */
    }

    .selector2 {
        /* this will NOT be ignored */
    }

    /* uncss:ignore start */

    /* all rules in here will be ignored */

    /* uncss:ignore end */

js
    'use strict';

    module.exports = function (window) {
        window.document.querySelector('html').classList.add('no-csscalc', 'csscalc');
    };

js
    {
      inject: function(window){
        window.document.querySelector('html').classList.add('no-csscalc', 'csscalc');
      }
    }

• jsdom (object) (Supported only by API): Supply the options used to create the JSDOM pages (https://github.com/jsdom/jsdom). At the moment, config.resources is not yet supported.

• media (string[]): By default UnCSS processes only stylesheets with media query _all_, _screen_, and those without one. Specify here which others to include.

• report (boolean, default: true): Return the report object in callback.

• strictSSL (boolean, default: true): Disable SSL verification when retrieving html source

• stylesheets (string[]): Use these stylesheets instead of those extracted from the HTML files. Prepend paths with the file:// protocol to force use of local stylesheets, otherwise paths will be resolved as a browser would for an anchor tag href on the HTML page.

• uncssrc (string): Load all options from a JSON file. Regular expressions for the ignore and ignoreSheets options should be wrapped in quotation marks.

json
    {
        "ignore": [".unused", "/^#js/"],
        "stylesheets": ["css/override.css"]
    }

• userAgent (String, default: 'uncss'): The user agent string that jsdom should send when requesting pages. May be useful when loading markup from services which use user agent based device detection to serve custom markup to mobile devices. Defaults to uncss`.

As a PostCSS Plugin

UnCSS can be used as a PostCSS Plugin.

js
postcss([require('uncss').postcssPlugin]);

See PostCSS docs for examples for your environment.

Note: Depending on your environment, you might not be able to use uncss as a PostCSS plugin since the plugin is not directly exported. In such cases, use the wrapper library postcss-uncss.

Options

• html (string[]): provide a list of html files to parse for selectors and elements. Usage of globs is allowed.

• ignore (string[] | RegExp[]): provide a list of selectors that should not be removed by UnCSS. For example, styles added by user interaction with the page (hover, click), since those are not detectable by UnCSS yet. Both literal names and regex patterns are recognized. Otherwise, you can add a comment before specific selectors in your CSS:

css
    /* uncss:ignore */
    .selector1 {
        /* this rule will be ignored */
    }

    .selector2 {
        /* this will NOT be ignored */
    }

Example Configuration

js
{
  html: ['index.html', 'about.html', 'team/*.html'],
  ignore: ['.fade']
}

License

Copyright (c) 2019 Giacomo Martino. See the [LICENSE](/LICENSE.md) file for license rights and limitations (MIT).

Collapse