postcss-filter-plugins

What is postcss-filter-plugins?

The postcss-filter-plugins package is a PostCSS plugin that allows you to filter out other PostCSS plugins based on certain criteria. This can be useful for avoiding duplicate plugins, ensuring specific plugins are only applied once, or conditionally applying plugins based on certain conditions.

What are postcss-filter-plugins's main functionalities?

Filter out duplicate plugins

This feature allows you to filter out duplicate plugins from your PostCSS plugin list. In the example, the 'autoprefixer' plugin is included twice, but the filterPlugins function will exclude the duplicate.

const postcss = require('postcss');
const filterPlugins = require('postcss-filter-plugins');

const plugins = [
  require('autoprefixer'),
  require('autoprefixer'), // duplicate
  filterPlugins({
    exclude: ['autoprefixer']
  })
];

postcss(plugins).process(css).then(result => {
  console.log(result.css);
});

Conditionally apply plugins

This feature allows you to conditionally apply plugins based on custom logic. In the example, the 'autoprefixer' plugin is excluded if the NODE_ENV environment variable is set to 'production'.

const postcss = require('postcss');
const filterPlugins = require('postcss-filter-plugins');

const plugins = [
  require('autoprefixer'),
  filterPlugins({
    exclude: plugin => plugin.postcssPlugin === 'autoprefixer' && process.env.NODE_ENV === 'production'
  })
];

postcss(plugins).process(css).then(result => {
  console.log(result.css);
});

Other packages similar to postcss-filter-plugins

postcss-discard-duplicates

The postcss-discard-duplicates package is a PostCSS plugin that removes duplicate rules from your CSS. While it focuses on removing duplicate CSS rules rather than plugins, it can be used in conjunction with postcss-filter-plugins to ensure both CSS rules and plugins are not duplicated.

postcss-unique-selectors

The postcss-unique-selectors package is a PostCSS plugin that ensures all selectors within a rule are unique. This is somewhat similar to postcss-filter-plugins in that it helps to avoid redundancy, but it operates at the CSS selector level rather than the plugin level.

README

postcss-filter-plugins

Exclude/warn on duplicated PostCSS plugins.

Install

With npm do:

$ npm install postcss-filter-plugins --save

Example

Note that this plugin does not actually transform your CSS; instead, it ensures that plugins in the PostCSS instance are not duplicated. It is intended to be used by plugin packs such as cssnano or cssnext.

var counter = postcss.plugin('counter', function () {
    return function (css) {
        css.eachDecl('foo', function (decl) {
            let value = parseInt(decl.value, 10);
            value += 1;
            decl.value = String(value);
        });
    }
});

var css = 'h1 { foo: 1 }';
var out = postcss([
    filter(),
    counter(),
    counter()
]).process(css).css;

console.log(out);
// => h1 { foo: 2 }
// Note that you will get a PostCSS warning in the message registry

API

filterPlugins([options])

options

direction

Type: string
Default: 'both'

Pass 'forward', 'backward', or 'both' to customise the direction in which the plugin will look in the plugins array. See the tests for examples on how this works.

postcss([ filter({
    direction: 'forward'
}) ]).process(css).css);

exclude

Type: array
Default: [] (empty)

Plugins that should be excluded from the filter. Pass an array of plugin names.

postcss([ filter({
    exclude: ['postcss-cssstats']
}) ]).process(css).css);

silent

Type: boolean
Default: false

Set this to true to disable the plugin from emitting any PostCSS warnings.

postcss([ filter({
    silent: true
}) ]).process(css).css);

template

Type: function
Default: format function

This function will be passed each PostCSS plugin object. You are expected to return a string from each call, which is then used to warn the user about her duplicated plugins.

postcss([ filter({
    template: function (plugin) {
        return 'Duplicate plugin found: ' + plugin.postcssPlugin;
    }
}) ]).process(css).css);

Usage

See the PostCSS documentation for examples for your environment.

Contributors

Thanks goes to these wonderful people (emoji key):

Ben Briggs 💻 📖 👀 ⚠️	Maxime Thirouin 📖	Andreas Lind 💻	Ryan Zimmerman 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

License

MIT © Ben Briggs