www.aleph1.co.uk Git - yaffs-website/blob - node_modules/gulp-postcss/README.md

   1 # gulp-postcss [![Build Status](https://api.travis-ci.org/postcss/gulp-postcss.png)](https://travis-ci.org/postcss/gulp-postcss)
   2
   3 [PostCSS](https://github.com/postcss/postcss) gulp plugin to pipe CSS through
   4 several plugins, but parse CSS only once.
   5
   6 ## Install
   7
   8     $ npm install --save-dev gulp-postcss
   9
  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.
  11
  12 ## Basic usage
  13
  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.
  17
  18 ```js
  19 var postcss = require('gulp-postcss');
  20 var gulp = require('gulp');
  21
  22 gulp.task('css', function () {
  23     return gulp.src('./src/*.css')
  24         .pipe(postcss())
  25         .pipe(gulp.dest('./dest'));
  26 });
  27 ```
  28
  29 ## Passing plugins directly
  30
  31 ```js
  32 var postcss = require('gulp-postcss');
  33 var gulp = require('gulp');
  34 var autoprefixer = require('autoprefixer');
  35 var cssnano = require('cssnano');
  36
  37 gulp.task('css', function () {
  38     var plugins = [
  39         autoprefixer({browsers: ['last 1 version']}),
  40         cssnano()
  41     ];
  42     return gulp.src('./src/*.css')
  43         .pipe(postcss(plugins))
  44         .pipe(gulp.dest('./dest'));
  45 });
  46 ```
  47
  48 ## Passing additional options to PostCSS
  49
  50 The second optional argument to gulp-postcss is passed to PostCSS.
  51
  52 This, for instance, may be used to enable custom parser:
  53
  54 ```js
  55 var gulp = require('gulp');
  56 var postcss = require('gulp-postcss');
  57 var nested = require('postcss-nested');
  58 var sugarss = require('sugarss');
  59
  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'));
  65 });
  66 ```
  67
  68 ## Using a custom processor
  69
  70 ```js
  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, {
  77                 prop: '-ms-filter',
  78                 value: '"progid:DXImageTransform.Microsoft.Alpha(Opacity=' + (parseFloat(decl.value) * 100) + ')"'
  79             });
  80         }
  81     });
  82 };
  83
  84 gulp.task('css', function () {
  85     var plugins = [
  86         cssnext({browsers: ['last 1 version']}),
  87         opacity
  88     ];
  89     return gulp.src('./src/*.css')
  90         .pipe(postcss(plugins))
  91         .pipe(gulp.dest('./dest'));
  92 });
  93 ```
  94
  95 ## Source map support
  96
  97 Source map is disabled by default, to extract map use together
  98 with [gulp-sourcemaps](https://github.com/floridoo/gulp-sourcemaps).
  99
 100 ```js
 101 return gulp.src('./src/*.css')
 102     .pipe(sourcemaps.init())
 103     .pipe(postcss(plugins))
 104     .pipe(sourcemaps.write('.'))
 105     .pipe(gulp.dest('./dest'));
 106 ```
 107
 108 ## Advanced usage
 109
 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:
 114
 115 ```js
 116 var gulp = require('gulp');
 117 var postcss = require('gulp-postcss');
 118
 119 gulp.task('css', function () {
 120     function callback(file) {
 121         return {
 122             plugins: [
 123                 require('postcss-import')({ root: file.dirname }),
 124                 require('postcss-modules')
 125             ],
 126             options: {
 127                 parser: file.extname === '.sss' ? require('sugarss') : false
 128             }
 129         }
 130     }
 131     return gulp.src('./src/*.css')
 132         .pipe(postcss(callback))
 133         .pipe(gulp.dest('./dest'));
 134 });
 135 ```
 136
 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.
 140
 141 ```js
 142 var gulp = require('gulp');
 143 var postcss = require('gulp-postcss');
 144
 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'));
 150 });
 151 ```
 152
 153 ```js
 154 module.exports = function (ctx) {
 155     var file = ctx.file;
 156     var options = ctx.options;
 157     return {
 158         parser: file.extname === '.sss' ? : 'sugarss' : false,
 159         plugins: {
 160            'postcss-import': { root: file.dirname }
 161            'postcss-modules': options.modules ? {} : false
 162         }
 163     }
 164 })
 165 ```
 166
 167 ## Changelog
 168
 169 * 6.3.0
 170   * Integrated with postcss-load-config
 171   * Added a callback to configure postcss on per-file-basis
 172   * Dropped node 0.10 support
 173
 174 * 6.2.0
 175   * Fix syntax error message for PostCSS 5.2 compatibility
 176
 177 * 6.1.1
 178   * Fixed the error output
 179
 180 * 6.1.0
 181   * Support for `null` files
 182   * Updated dependencies
 183
 184 * 6.0.1
 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
 187
 188 * 6.0.0
 189   * Updated PostCSS to version 5.0.0
 190
 191 * 5.1.10
 192   * Use autoprefixer in README
 193
 194 * 5.1.9
 195   * Prevent unhandled exception of the following pipes from being suppressed by Promise
 196
 197 * 5.1.8
 198   * Prevent stream’s unhandled exception from being suppressed by Promise
 199
 200 * 5.1.7
 201   * Updated direct dependencies
 202
 203 * 5.1.6
 204   * Updated `CssSyntaxError` check
 205
 206 * 5.1.4
 207   * Simplified error handling
 208   * Simplified postcss execution with object plugins
 209
 210 * 5.1.3 Updated travis banner
 211
 212 * 5.1.2 Transferred repo into postcss org on github
 213
 214 * 5.1.1
 215   * Allow override of `to` option
 216
 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
 221
 222 * 5.0.1
 223   * Fix to support object plugins
 224
 225 * 5.0.0
 226   * Use async API
 227
 228 * 4.0.3
 229   * Fixed bug with relative source map
 230
 231 * 4.0.2
 232   * Made PostCSS a simple dependency, because peer dependency is deprecated
 233
 234 * 4.0.1
 235   * Made PostCSS 4.x a peer dependency
 236
 237 * 4.0.0
 238   * Updated PostCSS to 4.0
 239
 240 * 3.0.0
 241   * Updated PostCSS to 3.0 and fixed tests
 242
 243 * 2.0.1
 244   * Added Changelog
 245   * Added example for a custom processor in README
 246
 247 * 2.0.0
 248   * Disable source map by default
 249   * Test source map
 250   * Added Travis support
 251   * Use autoprefixer-core in README
 252
 253 * 1.0.2
 254   * Improved README
 255
 256 * 1.0.1
 257   * Don't add source map comment if used with gulp-sourcemaps
 258
 259 * 1.0.0
 260   * Initial release