1 # gulp-postcss [![Build Status](https://api.travis-ci.org/postcss/gulp-postcss.png)](https://travis-ci.org/postcss/gulp-postcss)
3 [PostCSS](https://github.com/postcss/postcss) gulp plugin to pipe CSS through
4 several plugins, but parse CSS only once.
8 $ npm install --save-dev gulp-postcss
10 Install required [postcss plugins](https://www.npmjs.com/browse/keyword/postcss-plugin) separately. E.g. for autoprefixer, you need to install [autoprefixer](https://github.com/postcss/autoprefixer) package.
14 The configuration is loaded automatically from `postcss.config.js`
15 as [described here](https://www.npmjs.com/package/postcss-load-config),
16 so you don't have to specify any options.
19 var postcss = require('gulp-postcss');
20 var gulp = require('gulp');
22 gulp.task('css', function () {
23 return gulp.src('./src/*.css')
25 .pipe(gulp.dest('./dest'));
29 ## Passing plugins directly
32 var postcss = require('gulp-postcss');
33 var gulp = require('gulp');
34 var autoprefixer = require('autoprefixer');
35 var cssnano = require('cssnano');
37 gulp.task('css', function () {
39 autoprefixer({browsers: ['last 1 version']}),
42 return gulp.src('./src/*.css')
43 .pipe(postcss(plugins))
44 .pipe(gulp.dest('./dest'));
48 ## Passing additional options to PostCSS
50 The second optional argument to gulp-postcss is passed to PostCSS.
52 This, for instance, may be used to enable custom parser:
55 var gulp = require('gulp');
56 var postcss = require('gulp-postcss');
57 var nested = require('postcss-nested');
58 var sugarss = require('sugarss');
60 gulp.task('default', function () {
61 var plugins = [nested];
62 return gulp.src('in.sss')
63 .pipe(postcss(plugins, { parser: sugarss }))
64 .pipe(gulp.dest('out'));
68 ## Using a custom processor
71 var postcss = require('gulp-postcss');
72 var cssnext = require('postcss-cssnext');
73 var opacity = function (css, opts) {
74 css.eachDecl(function(decl) {
75 if (decl.prop === 'opacity') {
76 decl.parent.insertAfter(decl, {
78 value: '"progid:DXImageTransform.Microsoft.Alpha(Opacity=' + (parseFloat(decl.value) * 100) + ')"'
84 gulp.task('css', function () {
86 cssnext({browsers: ['last 1 version']}),
89 return gulp.src('./src/*.css')
90 .pipe(postcss(plugins))
91 .pipe(gulp.dest('./dest'));
97 Source map is disabled by default, to extract map use together
98 with [gulp-sourcemaps](https://github.com/floridoo/gulp-sourcemaps).
101 return gulp.src('./src/*.css')
102 .pipe(sourcemaps.init())
103 .pipe(postcss(plugins))
104 .pipe(sourcemaps.write('.'))
105 .pipe(gulp.dest('./dest'));
110 If you want to configure postcss on per-file-basis, you can pass a callback
111 that receives [vinyl file object](https://github.com/gulpjs/vinyl) and returns
112 `{ plugins: plugins, options: options }`. For example, when you need to
113 parse different extensions differntly:
116 var gulp = require('gulp');
117 var postcss = require('gulp-postcss');
119 gulp.task('css', function () {
120 function callback(file) {
123 require('postcss-import')({ root: file.dirname }),
124 require('postcss-modules')
127 parser: file.extname === '.sss' ? require('sugarss') : false
131 return gulp.src('./src/*.css')
132 .pipe(postcss(callback))
133 .pipe(gulp.dest('./dest'));
137 The same result may be achieved with
138 [`postcss-load-config`](https://www.npmjs.com/package/postcss-load-config),
139 because it receives `ctx` with the context options and the vinyl file.
142 var gulp = require('gulp');
143 var postcss = require('gulp-postcss');
145 gulp.task('css', function () {
146 var contextOptions = { modules: true };
147 return gulp.src('./src/*.css')
148 .pipe(postcss(contextOptions))
149 .pipe(gulp.dest('./dest'));
154 module.exports = function (ctx) {
156 var options = ctx.options;
158 parser: file.extname === '.sss' ? : 'sugarss' : false,
160 'postcss-import': { root: file.dirname }
161 'postcss-modules': options.modules ? {} : false
170 * Integrated with postcss-load-config
171 * Added a callback to configure postcss on per-file-basis
172 * Dropped node 0.10 support
175 * Fix syntax error message for PostCSS 5.2 compatibility
178 * Fixed the error output
181 * Support for `null` files
182 * Updated dependencies
185 * Added an example and a test to pass options to PostCSS (e.g. `syntax` option)
186 * Updated vinyl-sourcemaps-apply to 0.2.0
189 * Updated PostCSS to version 5.0.0
192 * Use autoprefixer in README
195 * Prevent unhandled exception of the following pipes from being suppressed by Promise
198 * Prevent stream’s unhandled exception from being suppressed by Promise
201 * Updated direct dependencies
204 * Updated `CssSyntaxError` check
207 * Simplified error handling
208 * Simplified postcss execution with object plugins
210 * 5.1.3 Updated travis banner
212 * 5.1.2 Transferred repo into postcss org on github
215 * Allow override of `to` option
217 * 5.1.0 PostCSS Runner Guidelines
218 * Set `from` and `to` processing options
219 * Don't output js stack trace for `CssSyntaxError`
220 * Display `result.warnings()` content
223 * Fix to support object plugins
229 * Fixed bug with relative source map
232 * Made PostCSS a simple dependency, because peer dependency is deprecated
235 * Made PostCSS 4.x a peer dependency
238 * Updated PostCSS to 4.0
241 * Updated PostCSS to 3.0 and fixed tests
245 * Added example for a custom processor in README
248 * Disable source map by default
250 * Added Travis support
251 * Use autoprefixer-core in README
257 * Don't add source map comment if used with gulp-sourcemaps