PostCSS Comments

PostCSS plugin to prepend and append comments to CSS rules.

Description

Some PostCSS plugins require to add comments to the CSS code to be able to perform their work (e.g. RTLCSS or PostCSS RTLCSS). But if the CSS code is coming from a third-party library or a CSS-in-JS framework it is impossible to modify the CSS source to add comments. In these cases, postcss-comments could be helpful to prepend or append comments to CSS rules selecting them using strings or regular expressions.

Install

npm

npm install postcss-comments --save-dev

yarn

yarn add postcss-comments -D

Usage with commonJS

const postcss = require('postcss');
const postcssComments = require('postcss-comments');

const result = postcss([
    postcssComments({
        rulesMatchers: [
            /* rulesMatchers */
        ]
    })
]).process(cssInput);

const commentedCSS = result.css;

Usage with ES6 modules

import postcss from 'postcss';
import postcssComments from 'postcss-comments';

const result = postcss([
    postcssComments({
        rulesMatchers: [
            /* rulesMatchers */
        ]
    })
]).process(cssInput);

const commentedCSS = result.css;

Usage in Webpack with postcss-loader

rules: [
    {
        test: /\.css$/,
        use: [
            { loader: 'style-loader' },
            { loader: 'css-loader' },
            {
                loader: 'postcss-loader',
                options: {
                    postcssOptions: {
                        plugins: [
                            postcssComments({
                                rulesMatchers: [
                                    /* rulesMatchers */
                                ]
                            })
                        ]
                    }
                }
            }
        ]
    }
]

Rules Matchers

rulesMatchers consist on an array of objects, each one describing one matcher.

{
    matcher: string | RegExp | (string | RegExp)[];
    prepend?: string;
    append?: string;
}

Examples

Input

.test1, .test2 {
    color: #666;
    padding-right: 20px;
    width: 100%;
}

.link {
    color: red;
}

.link:hover {
    color: red;
}

.link:visited {
    color: red;
}

.test-class {
    text-align: left;
    height: 100px;
}

Using string rule matchers

String matchers will match a rule if the entire selector of the rule matches exactly with the string.

postcssComments({
    rulesMatchers: [
       {
            matcher: ['.link', '.test-class'],
            prepend: 'Using an array of string matchers'
       },
       {
            matcher: '.link:visited',
            append: 'Using a unique string matcher'
       }
    ]
})

Output

.test1, .test2 {
    color: #666;
    padding-right: 20px;
    width: 100%;
}

/* Using an array of string matchers */
.link {
    color: red;
}

.link:hover {
    color: red;
}

.link:visited {
    color: red;
}
/* Using a unique string matcher */

/* Using an array of string matchers */
.test-class {
    text-align: left;
    height: 100px;
}

Using RegExp rule matchers

Regular Expressions matchers are more flexible. They allow one to match rules without specifying exactly the string of their selectors using a Regular Expression pattern instead.

postcssComments({
    rulesMatchers: [
       {
            matcher: [/^\.test\d+/, /^\.link:\w+$/],
            prepend: 'Using an array of RegExp matchers'
       },
       {
            matcher: /\.test-\w+$/,
            append: 'Using a single regular expression'
       }
    ]
})

Output

/* Using an array of RegExp matchers */
.test1, .test2 {
    color: #666;
    padding-right: 20px;
    width: 100%;
}

.link {
    color: red;
}

/* Using an array of RegExp matchers */
.link:hover {
    color: red;
}

/* Using an array of RegExp matchers */
.link:visited {
    color: red;
}

.test-class {
    text-align: left;
    height: 100px;
}
/* Using a single regular expression */

Notes

1. String matchers and Regular Expression matchers can be mixed in the same macther array.
2. Only the first matcher is used. If a rule matches a matcher, the append or prepend comments are inserted and it doesn‘t continue checking the next matchers on the array.
3. Regular Expressions matchers cannot have flags, if you set flags, they will be ignored.
4. If you do not use PostCSS, add it according to official docs and set this plugin in settings.