Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here

gulp-postcss

Pipe CSS through PostCSS processors with a single parse

Subscribe to updates I use gulp-postcss


Statistics on gulp-postcss

Number of watchers on Github 571
Number of open issues 3
Average time to close an issue 21 days
Main language JavaScript
Average time to merge a PR 2 days
Open pull requests 5+
Closed pull requests 13+
Last commit almost 2 years ago
Repo Created about 5 years ago
Repo Last Updated over 1 year ago
Size 85 KB
Organization / Authorpostcss
Latest Release7.0.1
Contributors8
Page Updated
Do you use gulp-postcss? Leave a review!
View open issues (3)
View gulp-postcss activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating gulp-postcss for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

gulp-postcss

Build Status Coverage Status

PostCSS gulp plugin to pipe CSS through several plugins, but parse CSS only once.

Install

$ npm install --save-dev gulp-postcss

Install required postcss plugins separately. E.g. for autoprefixer, you need to install autoprefixer package.

Basic usage

The configuration is loaded automatically from postcss.config.js as described here, so you don't have to specify any options.

var postcss = require('gulp-postcss');
var gulp = require('gulp');

gulp.task('css', function () {
    return gulp.src('./src/*.css')
        .pipe(postcss())
        .pipe(gulp.dest('./dest'));
});

Passing plugins directly

var postcss = require('gulp-postcss');
var gulp = require('gulp');
var autoprefixer = require('autoprefixer');
var cssnano = require('cssnano');

gulp.task('css', function () {
    var plugins = [
        autoprefixer({browsers: ['last 1 version']}),
        cssnano()
    ];
    return gulp.src('./src/*.css')
        .pipe(postcss(plugins))
        .pipe(gulp.dest('./dest'));
});

Passing additional options to PostCSS

The second optional argument to gulp-postcss is passed to PostCSS.

This, for instance, may be used to enable custom parser:

var gulp = require('gulp');
var postcss = require('gulp-postcss');
var nested = require('postcss-nested');
var sugarss = require('sugarss');

gulp.task('default', function () {
    var plugins = [nested];
    return gulp.src('in.sss')
        .pipe(postcss(plugins, { parser: sugarss }))
        .pipe(gulp.dest('out'));
});

Using a custom processor

var postcss = require('gulp-postcss');
var cssnext = require('postcss-cssnext');
var opacity = function (css, opts) {
    css.eachDecl(function(decl) {
        if (decl.prop === 'opacity') {
            decl.parent.insertAfter(decl, {
                prop: '-ms-filter',
                value: '"progid:DXImageTransform.Microsoft.Alpha(Opacity=' + (parseFloat(decl.value) * 100) + ')"'
            });
        }
    });
};

gulp.task('css', function () {
    var plugins = [
        cssnext({browsers: ['last 1 version']}),
        opacity
    ];
    return gulp.src('./src/*.css')
        .pipe(postcss(plugins))
        .pipe(gulp.dest('./dest'));
});

Source map support

Source map is disabled by default, to extract map use together with gulp-sourcemaps.

return gulp.src('./src/*.css')
    .pipe(sourcemaps.init())
    .pipe(postcss(plugins))
    .pipe(sourcemaps.write('.'))
    .pipe(gulp.dest('./dest'));

Advanced usage

If you want to configure postcss on per-file-basis, you can pass a callback that receives vinyl file object and returns { plugins: plugins, options: options }. For example, when you need to parse different extensions differntly:

var gulp = require('gulp');
var postcss = require('gulp-postcss');

gulp.task('css', function () {
    function callback(file) {
        return {
            plugins: [
                require('postcss-import')({ root: file.dirname }),
                require('postcss-modules')
            ],
            options: {
                parser: file.extname === '.sss' ? require('sugarss') : false
            }
        }
    }
    return gulp.src('./src/*.css')
        .pipe(postcss(callback))
        .pipe(gulp.dest('./dest'));
});

The same result may be achieved with postcss-load-config, because it receives ctx with the context options and the vinyl file.

var gulp = require('gulp');
var postcss = require('gulp-postcss');

gulp.task('css', function () {
    var contextOptions = { modules: true };
    return gulp.src('./src/*.css')
        .pipe(postcss(contextOptions))
        .pipe(gulp.dest('./dest'));
});
module.exports = function (ctx) {
    var file = ctx.file;
    var options = ctx.options;
    return {
        parser: file.extname === '.sss' ? : 'sugarss' : false,
        plugins: {
           'postcss-import': { root: file.dirname }
           'postcss-modules': options.modules ? {} : false
        }
    }
})

Changelog

  • 7.0.1

    • Drop dependency on gulp-util
  • 7.0.0

    • Bump PostCSS to 6.0
    • Smaller module size
    • Use eslint instead of jshint
  • 6.4.0

    • Add more details to PluginError object
  • 6.3.0

    • Integrated with postcss-load-config
    • Added a callback to configure postcss on per-file-basis
    • Dropped node 0.10 support
  • 6.2.0

    • Fix syntax error message for PostCSS 5.2 compatibility
  • 6.1.1

    • Fixed the error output
  • 6.1.0

    • Support for null files
    • Updated dependencies
  • 6.0.1

    • Added an example and a test to pass options to PostCSS (e.g. syntax option)
    • Updated vinyl-sourcemaps-apply to 0.2.0
  • 6.0.0

    • Updated PostCSS to version 5.0.0
  • 5.1.10

    • Use autoprefixer in README
  • 5.1.9

    • Prevent unhandled exception of the following pipes from being suppressed by Promise
  • 5.1.8

    • Prevent streams unhandled exception from being suppressed by Promise
  • 5.1.7

    • Updated direct dependencies
  • 5.1.6

    • Updated CssSyntaxError check
  • 5.1.4

    • Simplified error handling
    • Simplified postcss execution with object plugins
  • 5.1.3 Updated travis banner

  • 5.1.2 Transferred repo into postcss org on github

  • 5.1.1

    • Allow override of to option
  • 5.1.0 PostCSS Runner Guidelines

    • Set from and to processing options
    • Don't output js stack trace for CssSyntaxError
    • Display result.warnings() content
  • 5.0.1

    • Fix to support object plugins
  • 5.0.0

    • Use async API
  • 4.0.3

    • Fixed bug with relative source map
  • 4.0.2

    • Made PostCSS a simple dependency, because peer dependency is deprecated
  • 4.0.1

    • Made PostCSS 4.x a peer dependency
  • 4.0.0

    • Updated PostCSS to 4.0
  • 3.0.0

    • Updated PostCSS to 3.0 and fixed tests
  • 2.0.1

    • Added Changelog
    • Added example for a custom processor in README
  • 2.0.0

    • Disable source map by default
    • Test source map
    • Added Travis support
    • Use autoprefixer-core in README
  • 1.0.2

    • Improved README
  • 1.0.1

    • Don't add source map comment if used with gulp-sourcemaps
  • 1.0.0

    • Initial release
gulp-postcss open issues Ask a question     (View All Issues)
  • about 3 years Add more details to `PluginError` object
  • about 3 years I need a way to disable the error output
gulp-postcss open pull requests (View All Pulls)
  • Error details
  • Option warn
  • Test case fix for warnings
  • #94 fix test test fail
  • Output result of postcss. #105
gulp-postcss questions on Stackoverflow (View All Questions)
  • gulp postcss-simple-vars throws error at // comments
  • Gulp PostCSS Plugin Options
  • Gulp, postcss, sourcemaps, and autoprefixer: maps not showing in dev tools
  • gulp postcss rem to pixel fall back
gulp-postcss list of languages used
gulp-postcss latest release notes
7.0.1 7.0.1
  • Drop dependency on gulp-util
7.0.0
  • Bump PostCSS to 6.0
  • Smaller module size
  • Use eslint instead of jshint
6.4.0
  • Add more details to PluginError object
Other projects in JavaScript