silvermine / postcss-css-var-fallback

PostCSS plugin to insert fallbacks for CSS Custom Properties

PostCSS CSS Var Fallback

PostCSS plugin to insert fallbacks for CSS vars.

.foo {
   /* Input example */
   color: var(--color, #4a6da7);
}

.foo {
   /* Output example */
   color: #4a6da7;
   color: var(--color, #4a6da7);
}

Usage

Step 1: Install plugin:

npm install --save-dev postcss @silvermine/postcss-css-var-fallback

Step 2: Check you project for existed PostCSS config: postcss.config.js in the project root, "postcss" section in package.json or postcss in bundle config.

If you do not use PostCSS, add it according to official docs and set this plugin in settings.

Step 3: Add the plugin to plugins list:

module.exports = {
  plugins: [
+   require('@silvermine/postcss-css-var-fallback'),
    require('autoprefixer')
  ]
}

Limitations

Be aware that this plugin does not add a fallback for declarations with var statements when there is more than one declaration for a given CSS property in a single rule.

For example, this plugin will not add a fallback for the var statement in this case:

.example {
   color: red;
   color: var(--textColor, #333);
}

The plugin assumes that the previous color: red declaration is a fallback. This prevents the plugin from having to parse the var(--textColor, #333) statement and compare the fallback there with any other color: declaration values. We found that such a check impacted performance enough that it was not worth the cost.

To avoid incorrect or missing fallbacks, ensure that the CSS that you write does not have extraneous/duplicate declarations for the same CSS property.