npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

gulp-postcss

v10.0.0

Published

PostCSS gulp plugin

Downloads

829,452

Readme

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 postcss 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'));
});

Using with .pcss extension

For using gulp-postcss to have input files in .pcss format and get .css output need additional library like gulp-rename.

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

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

This is done for more explicit transformation. According to gulp plugin guidelines

Your plugin should only do one thing, and do it well.

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'));
});

If you are using a postcss.config.js file, you can pass PostCSS options as the first argument to gulp-postcss.

This, for instance, will let PostCSS know what the final file destination path is, since it will be unaware of the path given to gulp.dest():

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

gulp.task('default', function () {
    return gulp.src('in.scss')
        .pipe(postcss({ to: 'out/in.css' }))
        .pipe(gulp.dest('out'));
});

Using a custom processor

var postcss = require('gulp-postcss');
var cssnext = require('postcss-cssnext');
var opacity = function (css, opts) {
    css.walkDecls(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'));
});
// postcss.config.js or .postcssrc.js
module.exports = function (ctx) {
    var file = ctx.file;
    var options = ctx;
    return {
        parser: file.extname === '.sss' ? : 'sugarss' : false,
        plugins: {
           'postcss-import': { root: file.dirname }
           'postcss-modules': options.modules ? {} : false
        }
    }
};

Changelog

  • 10.0.0

    • Released with the same changes as 9.1.0
  • 9.1.0 deprecated, because it breaks semver by dropping support for node <18

    • Bump postcss-load-config to ^5.0.0
    • Ensure options are passed to plugins when using postcss.config.js #170
    • Update deps
    • Drop support for node <18
    • Add flake.nix for local dev with nix develop
  • 9.0.1

    • Bump postcss-load-config to ^3.0.0
  • 9.0.0

    • Bump PostCSS to 8.0
    • Drop Node 6 support
    • PostCSS is now a peer dependency
  • 8.0.0

    • Bump PostCSS to 7.0
    • Drop Node 4 support
  • 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 stream’s 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