Home

Awesome

grunt-postcss

npm Version Build Status

Apply several post-processors to your CSS using PostCSS.

Getting Started

This plugin requires Grunt 1.0.3 or above.

Note: As of v3.0.0, Node.js 10.x or above is required.

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm i --save-dev postcss @lodder/grunt-postcss

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('@lodder/grunt-postcss');

Usage

npm i @lodder/grunt-postcss autoprefixer cssnano
grunt.initConfig({
  postcss: {
    options: {
      map: true, // inline sourcemaps

      // or
      map: {
          inline: false, // save all sourcemaps as separate files...
          annotation: 'dist/css/maps/' // ...to the specified directory
      },

      processors: [
        require('autoprefixer')(),
        require('cssnano')() // minify the result
      ]
    },
    dist: {
      src: 'css/*.css'
    }
  }
});

Options

Post-processors options

require('postcss-plugin')({option: value})

Plugin options

options.processors

An array of PostCSS compatible post-processors. You can also use a function that returns an array of PostCSS post-processors.

options.map

If the map option isn't defined or is set to false, PostCSS won't create or update sourcemaps.

If true is specified, PostCSS will try to locate a sourcemap from a previous compilation step using an annotation comment (e.g. from Sass) and create a new sourcemap based on the found one (or just create a new inlined sourcemap). The created sourcemap can be either a separate file or an inlined map depending on what the previous sourcemap was.

You can gain more control over sourcemap generation by assigning an object to the map option:

options.diff

Set it to true if you want to get a patch file:

options: {
  diff: true // or 'custom/path/to/file.css.patch'
}

You can also specify a path where you want the file to be saved.

options.sequential

By default grunt-postcss will load all passed CSS files and immediately process them. Set this to true if you want files to be processed one by one. This can help in case when you have a lot of CSS files and processing them causes an out of memory error.

options.failOnError

Set it to true if you want grunt to exit with an error on detecting a warning or error.

options.writeDest

Set it to false if you do not want the destination files to be written. This does not affect the processing of the map and diff options.

options.onError

This function is called when an error occurs and passes the error data.

options.syntax, options.parser, options.stringifier

Options to control PostCSS custom syntaxes.

options: {
  parser: require('postcss-safe-parser') // instead of a removed `safe` option
}
options: {
  syntax: require('postcss-scss') // work with SCSS directly
}

Why would I use this?

Unlike the traditional approach with separate plugins, grunt-postcss allows you to parse and save CSS only once applying all post-processors in memory and thus reducing your build time. PostCSS is also a simple tool for writing your own CSS post-processors.

How to migrate from grunt-autoprefixer?

Autoprefixer is a PostCSS plugin, so first replace grunt-autoprefixer with grunt-postcss and autoprefixer plugin.

npm remove --save-dev grunt-autoprefixer
npm install --save-dev @lodder/grunt-postcss autoprefixer

Assuming you have a config like this:

autoprefixer: {
  options: {
    map: true,
    browsers: ['last 1 version']
  },
  dist: {
    src: '...'
  }
}

Replace it with:

postcss: {
  options: {
    map: true,
    processors: [
      require('autoprefixer')()
    ]
  },
  dist: {
    src: '...'
  }
}

And add the browsers to either your package.json or .browserslistrc file.

browsers, cascade and remove options are plugin-specific, so we pass them as an argument while require the plugin.