@gojek/postcss-customprop-validate

postcss-customprop-validate

PostCSS plugin to scan a CSS file and validate the CSS Custom Properties' default values.

Use CSS Custom Properties without worrying about the correctness of the default values. This plugin will either auto-correct the CSS file or return an array of all the incorrect ones.

Usage

Install with npm:

npm install @gojek/postcss-customprop-validate --save-dev

or with yarn:

yarn add @gojek/postcss-customprop-validate --dev

PostCSS

Add PostCSS to your build tool:

npm install postcss --save-dev

Use postcss-customprop-validate as a plugin:

import postcss from 'postcss'
import validate from '@gojek/postcss-customprop-validate'

postcss([
  validate(/* options */)
])

Rollup

Add Rollup Plugin PostCSS to your build tool:

npm install rollup-plugin-postcss --save-dev

Use postcss-customprop-validate in your rollup.config.js:

import postcss from 'rollup-plugin-postcss'
import validate from '@gojek/postcss-customprop-validate'

export default {
  plugins: [
    postcss({
      plugins: [
        validate(/* options */)
      ]
    })
  ]
}

List of options

Option	Required	Description	Default
variables	true	JSON containing the custom properties with their default values. The plugin will throw an error if not passed	N.A.
write	false	Rewrites the CSS file with correct values	false
callback	false	Calls callback with an array of incorrect custom properties after the plugin runs.	() => {}

Examples

import postcss from "postcss"
import validate from "@gojek/postcss-customprop-validate"

/** CSS with incorrect default values of custom properties */
const css2 = `.Danger {
  color: var(--color-red, red);
  border: var(--custom-border, var(--border-radius, 8px) solid var(--color-red, hsla(292, 56%, 33%, 1)));
}`

/** CSS custom properties JSON to validate values from */
const variables = {
  "--border-radius": "4px",
  "--color-red": "hsla(292, 56%, 33%, 1)",
  "--custom-border":
    "var(--border-radius, 4px) solid var(--color-red, hsla(292, 56%, 33%, 1))"
}

const logValues = arr => console.log(arr)

const process = await postcss([
  validate({ write: false, variables, callback: logValues })
]).process(css)

postcss-customprop-validate will read the CSS and log the result as:

[
  {
    path: { absolute path }, // the absolute path of the CSS file
    line: 2,
    key: '--color-red',
    current: 'red',
    expected: 'hsla(292, 56%, 33%, 1)'
  },
  {
    path: { absolute path }, // the absolute path of the CSS file
    line: 3,
    key: '--custom-border',
    current: 'var(--border-radius, 8px) solid var(--color-red, hsla(292, 56%, 33%, 1))',
    expected: 'var(--border-radius, 4px) solid var(--color-red, hsla(292, 56%, 33%, 1))'
  },
  {
    path: { absolute path }, // the absolute path of the CSS file
    line: 3,
    key: '--border-radius',
    current: '8px',
    expected: '4px'
  }
]