postcss-var-replace
v1.0.0
Published
PostCSS plugin to replace CSS variables with their static values
Downloads
68,099
Maintainers
Readme
postcss-var-replace
PostCSS plugin to replace CSS variables` with their static values.
This plugin provides a future-proof way of using most of CSS variables features, including selector cascading (with some caveats).
Requirements
This package requires an LTS Node version (v18.0.0+)
Install
npm add postcss-var-replace
Usage
For more general PostCSS usage, look here.
import postcss from 'postcss';
import { postcssVarReplace } from 'postcss-var-replace';
const input = `
:root {
--font-name: 'my-font-family-name';
}
@font-face {
font-family: var(--font-name);
src: url('myfont.woff2') format('woff2');
}`;
const { css } = postcss([postcssVarReplace()]).process(input);
console.log(css);
Options
preserve
Type: boolean
Default: false
Allows you to preserve custom properties & var() usage in output.
Possible values:
false
: Removes--var
declarations and replacesvar()
with their resolved/computed values.true
: Keepsvar()
declarations in the output and has the computed value as a fallback declaration. Also keeps computed--var
declarations.'computed'
: Keeps computed--var
declarations in the output. Handy to make them available to your JavaScript.(declaration) => boolean|'computed'
: function/callback to programmatically return whether preserve the respective declaration
preserveAtRulesOrder
Type: boolean
Default: false
Keeps your at-rules like media queries in the order to defined them.
Ideally, this would be defaulted to true
and it will be in the next major version. All of the tests expecations need to be updated and probably just drop support for preserveAtRulesOrder: false
preserveInjectedVariables
Type: boolean
Default: true
Whether to preserve the custom property declarations inserted via the variables
option from final output.
A typical use case is CSS Modules, where you would want to avoid
repeating custom property definitions in every module passed through this plugin. Setting this option to false
prevents JS-injected variables from appearing in output CSS.
import postcss from 'postcss';
import { postcssVarReplace } from 'postcss-var-replace';
postcss([
postcssVarReplace({
variables: {
'--some-var': '100px',
'--other-var': {
value: '#00ff00'
},
'--important-var': {
value: '#ff0000',
isImportant: true
}
}
})
]).process(css, opts);
variables
Type: object
Default: {}
Define an object map of variables in JavaScript that will be declared at the :root
scope.
Can be a simple key-value pair or an object with a value
property and an optional isImportant
bool property.
The object keys are automatically prefixed with --
(according to CSS custom property syntax) if you do not provide it.
Contributing, Working With This Repo
We 💛 contributions! After all, this is a community-driven project. We have no corporate sponsorship or backing. The maintainers and users keep this project going!
Please check out our Contribution Guide.
Attribution
This is a modern fork of https://github.com/MadLittleMods/postcss-css-variables