postcss-filter-stream

PostCSS Filter Stream

PostCSS plugin which allows you to blacklist files / folders that you don't want to process with a given PostCSS plugin.

import gulp from 'gulp';
import postcss from 'gulp-postcss';
import reporter from 'postcss-reporter';
import scss from 'postcss-scss';
import colorguard from 'colorguard';
import filterStream from 'postcss-filter-stream';

const processors = [
  // Ignore all files recursively in vendor folder.
  filterStream('**/css/vendor/**', colorguard()),
  reporter({ clearMessages: true })
];

gulp.task('css-lint', () => {
  return gulp.src('src/css/**/*.scss')
    .pipe(postcss(processors, { syntax: scss }))
});

Install

npm install --save-dev postcss-filter-stream

Syntax

filterStream(filter: string|Array<string>, postcssPlugin: Function)

The filter argument accepts a glob string or an array of glob strings. Globbing patterns:

• * matches any number of characters, but not /
• ? matches a single character, but not /
• ** matches any number of characters, including /, as long as it's the only thing in a path part
• {} allows for a comma-separated list of "or" expressions
• ! at the beginning of a pattern will negate the match

Please note the preceding **/ in the example. Use it if you don't want to specify the absolute path, that in my case would be: '/Users/tsm/Sites/__projects/gulp-starter/src/css/vendor/**'.

The postcssPlugin argument is basically any PostCSS plugin you choose to use. In the example you can see i do not want the colorguard plugin to check my .scss files in the css/vendor/ directory because i have Bootstrap, Font Awesome and other vendor sass files i choosed to compile at runtime. Of course i want to ignore these files because it is not my code, not my responsibility.

Examples

Ignore all .scss and .sass files recursively in vendor folder.

  filterStream('**/src/css/vendor/**/*.+(scss|sass)', postCssPlugin())

Ignore all files recursively in vendor and custom folders and _scaffolding.scss in common folder.

  filterStream([
    '**/src/css/vendor/**',
    '**/src/css/custom/**',
    '**/src/common/css/_scaffolding.scss'
  ], postCssPlugin())

Ignore all .scss and .sass files in vendor folder but the _font-awesome.scss file.

  filterStream([
    '**/src/css/vendor/*.+(scss|sass)',
    '!**/src/css/vendor/_font-awesome.scss'
  ], postCssPlugin())

Why a plugin like this exists?

Imagine you want to use a PostCSS plugin but you have to ignore some files / folders and the plugin's API doesnt't have support for that. What can you do? Probably use gulp-filter to filter the stream and apply .pipe(postcss(processors, { syntax: scss })) only for the filtered files. Of course if you use multiple PostCSS plugins that you want to run anyway you will have to restore the filtered stream and run postcss again .pipe(postcss(processors-2, { syntax: scss })). This is why a plugin like this exists.

Thanks

• Andrey Sitnik - For writing 80% of the code and order me to finish it. :)
• Ben Briggs - For the encouragement.