This is a simple boilerplate for using NPM and PostCSS to handle common front-end development environments
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

PostCSS NPM Boilerplate

This is a simple boilerplate for using NPM and PostCSS to handle common front-end development environments.


  1. Clone the repository
  • git clone
  1. (optional) Install Yarn Package Manager. Alternatively, you can use NPM as you may already be used to. I recommend Yarn for easier and more expedited package installation.
  2. Install dependencies
  • Using Yarn: yarn
  • Using NPM: npm install


This boilerplate features many features similar to Sass without including the entire feature set. I have hand-picked the functionality that I use most commonly in my projects.


Imports are handled similar to Sass. You can may import a file by doing the following:

@import "_variables.css";


$display: flex;

.element {
  display: $display;

Compiles To:

.element {
  display: flex;

Nested Elements

.element {
  &:hover {
    background: white;

  .element-child {
    position: relative;

Compiles to:

.element:hover {
  background: white;

.element .element-child {
  position: relative;


@each $icon in (foo, bar, baz) {
  .icon-$icon {
    background: url('path/to/$icon.png');

@for $index from 1 to 5 by 2 {
  .col-$index {
    width: $(index)0%;

Compiles to:

.icon-foo {
  background: url('path/to/foo.png');

.icon-bar {
  background: url('path/to/bar.png');

.icon-baz {
  background: url('path/to/baz.png');

.col-1 {
  width: 10%;

.col-3 {
  width: 30%;

.col-5 {
  width: 50%;

Custom Breakpoints

@custom-media --small-max (max-width: 30em);

@media (--small-max) {
  /* styles for small viewport */

Compiles to:

@media (max-width: 30em) {
  /* styles for small viewport */


This boilerplate relies only on NPM scripts as the build tool. Included build processes are as follows:

npm start

Compiles the /src/css/app.css file and outputs to /dist/css/app.css. This command watches the file tree inside of /src/css for changes and recompiles when necessary.

npm run build

Only compiles the /src/css/app.css file and outputs to /dist/css/app.css without watching the file tree.

npm run minify

Uses cssnano to minify the /dist/css/app.css file and output a minified version to /dist/css/app.min.css.

npm run stylefmt

Uses a combination of stylelint and stylemt PostCSS plugins to organize source CSS files according to style lint rules (located in .stylelintrc).

npm run compile

Runs the clean, build and stylefmt commands to clean the /dist directory as well as build distribution files and format source files.

npm run clean

Deletes all files from the /dist directory.


This boilerplate relies on the following PostCSS plugins: