Getting started with PostCSS: A quick guide for Sass users

Published in

Heresy Dev

3 min readApr 21, 2016

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. Any suggestions and comments please drop a tweet to @svileng — thanks!

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": [
    "autoprefixer",
    "postcss-import",
    "postcss-simple-vars",
    "postcss-extend",
    "postcss-nested",
    "postcss-mixins"
  ],
  "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.

Getting started with PostCSS: A quick guide for Sass users

Running PostCSS

Example PostCSS configuration

Further reading

Written by Svilen Gospodinov