Getting Started with PostCSS: A Quick Guide for Sass Users

Published on: 21 April 2016

This post was originally published on Medium. This the latest version which contains some minor changes.

You may have heard about PostCSS and how it is almost 2x faster than libsass (and 28x faster than Ruby Sass); or about its cssnext and CSS Modules support and extensible functionality. But have you had a chance to try it out?

PostCSS’s biggest strength—its modularity and plugin-oriented architecture—is also a downside. If you have been using Sass (which is the majority of designers and front-end developers) for your projects, you never had to configure anything—Sass comes with all functionality included, out-of-the-box. PostCSS, however, requires you to do some work. You have to choose from a seemingly endless list of plugins and put all pieces together yourself.

This guide provides (what I think is) a good base configuration for Sass users, so you can easily try out PostCSS and dive in the details later. Hope you find it useful.

Note: there are PostCSS projects that attempt to give you Sass-like functionality in a single plugin. I would personally avoid them and pick the plugins individually when I need a specific feature—this gives you more flexibility, and you can also use some new plugins that are even more powerful than their Sass equivalent.

Running PostCSS

There are a number of ways to run PostCSS. You can easily plug it into your Gulp or Webpack build process; for this guide, however, to keep things as simple as possible, we’re going to use PostCSS’s CLI. The majority of people would probably install it globally like so:

npm install -g postcss-cli

However, I recommend installing the runnable locally, so that it resides within the project you’re working on:

npm install --save-dev postcss-cli

And run it like so (from the main project directory):

./node_modules/.bin/postcss [options]

I find this approach better than managing versions of globally installed modules across projects. To make it even easier, you can add the following line to your “scripts” section in package.json:

  "name": "mysite",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "start": "node app.js",
    "postcss": "postcss --config postcss.json"
  "dependencies": {
    "conveyor-belt": "0.0.5",
    "express": "~4.9.0",
    "express-handlebars": "^2.0.1",
    "morgan": "~1.3.0"
  "devDependencies": {
    "postcss-cli": "^2.5.1",

Turns out you can omit ./node_modules/.bin and just call postcss here — thanks to vectorsize for the tip!

So from now on you can just run

npm run postcss

You have probably noticed the --config postcss.json argument—this is going to contain our PostCSS configuration.

Rather than passing lots of arguments in the command line/package.json file, we can specify everything within a single JSON file. Here’s the basic structure:

  "use": [],
  "input": "css/main.css",
  "output": "public/main.css",
  "local-plugins": true,
  "watch": true

While this is a valid example, it actually doesn’t do anything at all. Notice the empty use array. This is where we specify our PostCSS plugins that help us transform the input CSS and add functionality.

Example PostCSS configuration

If you’re coming from a Sass project, you’ll likely want to have:

  • CSS @imports
  • CSS @extends
  • $variables
  • Nested classes
  • Mixins
  • Autoprefixing

To get all that, you need to install the relevant modules:

Note: the plugins provide almost identical syntax to Sass. Some are slightly different (and in the case of postcss-mixins, much more powerful), so make sure to check the pages above for more info.

And to install them in one line:

npm install --save-dev postcss-import postcss-simple-vars postcss-extend postcss-nested postcss-mixins autoprefixer

Then update your postcss.json:

  "use": [
  "input": "css/main.css",
  "output": "public/main.css",
  "local-plugins": true,
  "watch": true,
  "autoprefixer": {
    "browsers": "> 5%"

Notice we added an extra key for autoprefixer — you can also use the json to configure individual plugins.

Now you can just do npm run postcss (there is currently no output in the Terminal, sadly, so you’ll just get a blank line) and it will automatically transform and watch the code for changes.

Further reading

Now that you have most of the things you need to get started using PostCSS, you may want to have a look at cssnext to start using CSS4 today, or have a look at the long list of language extensions, linters and optimisers currently available as plugins.

This work is licensed under the Creative Commons BY-SA 4.0 International License