Automatically removing unused CSS using Grunt

I have previously blogged about the importance of keeping your web pages lean and the impact that unused CSS can have on your page performance. Apart from causing cluttered files, unused CSS can can slow down page load times due to the unnecessary weight of the file. Google Chrome developer tools has some great features that can help you detect any unused CSS. By using the audit feature, you can view all the CSS selectors that arent used by the current web page. This feature is really handy, but it can be tedious to manually go through each page and remove the unused CSS.

Fortunately, the master that is Addy Osmani came up with a neat way of automating the removal process. This is where Grunt and the UnCSS plugin comes in. If you aren't familiar with Grunt, it is a JavaScript task runner that you can use to automate pretty much anything in your development workflow. It works together with Node.js and there are tons of great plugins available.

Grunt JavaScript Task Runner

In this post, I am going to run through the process of setting up Node.js on a Windows machine, installing Grunt and getting the UnCSS plugin running on a simple project. By the time you get to the end of this post, you should be able to automatically remove unused CSS from your stylesheets as well as minify them on the fly. You'll be pretty impressed with the results that we achieve!

The Example Project

For this example, I am using a simple HTML page that uses the Twitter Bootstrap CSS as a template plus some custom CSS. The combined weight of the CSS files is 124 KB.

Installing Node.js

In order to get Grunt running on your machine, you will need to install Node.js. Start by heading over to the Node.js website and download the latest distributable. It is easy to install and only takes a couple of minutes.

Installing Grunt

Next up, you will need to install Grunt. If you haven't used Grunt before, be sure to check out the Getting Started guide, as it is a useful guide to installing this and many other Grunt plugins. In order to install Grunt, fire up the Node.js command prompt that you have just installed. In the command prompt, type the following:

npm install -g grunt-cli

This will download and install Grunt for you - easy! Next, navigate to the folder that contains your source files that you wish to process. In my case, the command I type is:

cd C:\Dev\ExampleProject

With the Node.js command prompt still open, type in the following code:

npm install grunt-uncss grunt-contrib-cssmin --save-dev

This command will install the UnCSS package and the CSSMin package in your project folder. You will only need to do this the first time you configure your project. Before going any further, we need to create a Grunt.js file in the root of the project that we are working on. The Gruntfile.js is a valid JavaScript file that belongs in the root directory of your project. Think of it as a configuration file that you use to configure the different plugins, as well as the order that they run in. The Gruntfile.js should look something similar to the code below.

In the code above, I am configuring the UnCSS plugin to look at my index.html file, locate any CSS and spit out a version with all the unused CSS removed. The new CSS file will be created in a new folder called "cleancss". Next, the CSSmin plugin is configured to look at the clean CSS (tidy.css) and minify the file. Finally, in line 21 to 25, we load the two different plugins and register them.

All you need to do now is run Grunt.

Remove that dirty CSS!

In the Node.js command prompt, navigate to the folder that contains your source files. This should also be the same folder that contains a Gruntfile.js with the configuration settings for the project.

Running Grunt and UnCSS - Node.js

Once the files have been run through the plugins, the clean, minified CSS will be created in the folder that you specified in the gruntfile. The resulting CSS file that is created comes in at a tidy 5 KB, making a saving of 119 KB. That is a saving of over 95%!

As you can see, a simple change using this tool can make a significant difference to your page load times. It's a great tool that is packed with useful plugins - it is definitely worth using it on your next project.

Further Reading

Check out the other great plugins available for Grunt, as well as the UnCSS project on Github. For another detailed installation guide - try this link.


Chris - 3/24/2014
How does this work with classes that are toggled with JavaScript?

Matija Marohnic - 3/25/2014
Chris, I believe you have to ignore them via the appropriate grunt-uncss option. But yeah, you can easily miss something. I think this part should also be included in the article.

Arafath - 12/5/2014
how can remove all the css witch is not use in whole project?

Jake - 2/27/2015
Huge error when running the second grunt command. Very frustrating

Dean Hume - 2/27/2015
@Jake - what error are you getting exactly?

Bjorn - 3/16/2015
I'm getting a "local Npm module "grunt-uncss" not found. Is it installed? " error.. I did install with node.js with: npm install -g grunt-cli and npm install grunt-uncss grunt-contrib-cssmin --save-dev. But UnCSS package and the CSSMin package don't come in the project folder.. Can you help?

Mark - 3/24/2015
Gave this a shot on a bootstrap project with a theme and CSS 3 animations. Took 245KB down to 84KB and then barely allowed the site to function anymore. This isn't exactly a silver bullet, no surprise. But the grunt modules totalled about 80MB on disk after I was done playing around.

shawn - 8/19/2015
same as Bjorn - grunt-uncess not found

Steven Lutz - 9/4/2015
Windows 10 - Node.js not required at all, run all commands through the admin command prompt. 100% success - brought 128kb down to just over 11 My suggestion is to build, temporarily remove references to all JS - run the script - reinstate JS That procedure gave me 0 errors. Steven

Sunil - 2/1/2016
Actually this is not a comment, it is a question. I have successfully run this task uncss task and create a tidy.css in my project. What I am doing now, I'm including this tidy.css in my index.thml file and commenting all the css files. But UI of my project is getting distort. Please help and correct me if I'm doing anything wrong.

Leo - 12/5/2016
After fail cleaning hugh css file multiple time manually, I read this post. Many thanks, save my time!

Add your comment

300 Characters left

Please fill this in to confirm that you are human