postcss-short-css-vars

PostCSS plugin using short-css-vars to shorten the names of CSS variables in stylesheets.

CSS variables are renamed with a unique hash that is consistent across processed files. This allows you to have common style files that reference variables with varying values defined in theme files.

Installation

$ npm install postcss-short-css-vars --save-dev

Example

Input

:root {
 --long-variable-name-that-defines-a-particular-color: blue;
}

.my-class {
  color: var(--long-variable-name-that-defines-a-particular-color);
}

Output

:root {
 --1vf2dsn: blue;
}

.my-class {
  color: var(--1vf2dsn);
}

Usage

See the PostCSS docs for examples on how to use this plugin in different environments.

Options

This plugin supports all the utility options with the addition of a callback to retrieve the rename map.

callback

A callback can be provided which will be provided with an object to show what variables were renamed as.

{
  "long-variable-name-that-defines-a-particular-color": "1vf2dsn"
}

You can utilize this for logging or other tracking purposes.

const postcss = require('postcss');
const shortCssVars = require('postcss-short-css-vars');
const fs = require('fs');

postcss([shortCssVars({
  callback: map => {
    console.log(JSON.stringify(map));
    fs.writeFile('css-vars-map.json', JSON.stringify(map), 'utf8');    
  }
})])

formatter

See the utility for how the default formatting works. If you wish to use a different pattern, simply provide a different formatter function via options.

const postcss = require('postcss');
const shortCssVars = require('postcss-short-css-vars');
const fnv1a = require('fnv1a');

postcss([shortCssVars({
  formatter: name => fnv1a(name).toString(36)
})])

The name provided to the formatter is the variable name WITHOUT the '--' prefix. The return value should also be name-only. So my-custom-var rather than --my-custom-var.

ignore

If you need to avoid hashing certain variable names, you can ignore them with this option by either RegExp, function, or string (which will be turned into RegExp). This can be useful if you are referencing CSS Variables in an app, yet you do not have control over some of the declarations.

const postcss = require('postcss');
const shortCssVars = require('postcss-short-css-vars');

postcss([shortCssVars({
  ignore: /^third-party-theme/
})])

In another scenario, if you have several short variable names (for example --blue) you can use a function to ignore names by length.

postcss([shortCssVars({
  ignore: name => name.length <= 4
})])

The name provided to ignore is the variable name WITHOUT the '--' prefix. So blue rather than --blue.