princed / postcss-modules-values-replace

PostCSS plugin intended to replace CSS Modules values

PostCSS Modules Values Replace

PostCSS plugin to work around CSS Modules values limitations.

Replaces CSS Modules @values just as postcss-modules-values does, but without help of css-loader, so it could be used before other PostCSS plugins like postcss-calc.

Example:

/* constants.css */
@value unit: 8px;
@value footer-height: calc(unit * 5);

/* my-components.css */
@value unit, footer-height from "./constants.css";
@value component-height: calc(unit * 10);

.my-component {
  padding: unit;
  margin-top: footer-height;
  height: component-height;
}

yields my-components.css:

 @value unit, footer-height from "./constants.css";
 @value component-height: calc(8px * 10);

 .my-component {
   padding: 8px;
   margin-top: calc(8px * 5);
   height: calc(8px * 10);
 }

and leads to export of following values to JS:

{
    "unit": "8px",
    "footer-height": "calc(8px * 5)",
    "component-height": "calc(8px * 10)",
    ...
}

See how to export computed values in usage with calc example below.

Usage

Place it before other plugins:

postcss([ require('postcss-modules-values-replace'), require('postcss-calc') ]);

When using from webpack, pass its file system in postcss.config.js form:

module.exports = (ctx) => ({
   plugins: [
     require('postcss-modules-values-replace')({fs: ctx.webpack._compiler.inputFileSystem}),
     require('postcss-calc'),
  ]
});

See PostCSS docs for other examples for your environment.

Configuration params

fs Object

File system to use. To make it faster in webpack pass its file system to plugin. Cached Node's file system is used by default.

resolve Object

enhanced-resolve's configuration object, see there for possible options and defaults.

noEmitExports boolean

When enabled @value rules/declarations will be removed from the emitted output

Input:

@value myBrandColor blue;
@font-face {}

body { background: myBrandColor }

Output:

@font-face {}

body { background: blue }

preprocessValues boolean

When enabled, permit plugins defined earlier in the PostCSS pipeline to modify @value declarations before they are recorded by this plugin.

importsAsModuleRequests boolean

When enabled, value imports will be resolved as module requests, in line with css-loader's resolution logic as of 2.0.0. If your code is written with pre-2.0 import syntax, and utilises postcss-modules-tilda for compatibility, this option is not required.

replaceInSelectors boolean

When enabled, value usage within rule selectors will also be replaced by this plugin.

atRules Array<string>

You can pass a list of at-rules in which @value's should be replaced. Only @media rules will be processed by default. Note that passed array isn't merged with default ['media'] but overwrites it, so you'll need to include all the rules you want to be processed.

postcss([
  require('postcss-modules-values-replace')({ atRules: ['media', 'container']  })
]);

Input:

@value $tables from './breakpoints.css';

@container (width >= $tablet) {}

Output:

@container (width >= 768px) {}

calc() and @value

To enable calculations inside @value, enable media queries support in postcss-calc:

postcss([
  require('postcss-modules-values-replace'),
  require('postcss-calc')({mediaQueries: true})
])

or via postcss-cssnext:

postcss([
  require('postcss-modules-values-replace'),
  require('postcss-cssnext')({features: {calc: {mediaQueries: true}}})
])

Example with calc enabled:

/* constants.css */
@value unit: 8px;
@value footer-height: calc(unit * 5);

/* my-components.css */
@value unit, footer-height from "./constants.css";
@value component-height: calc(unit * 10);

.my-component {
  padding: unit;
  margin-top: footer-height;
  height: component-height;
}

yields my-components.css:

 @value unit, footer-height from "./constants.css";
 @value component-height: 80px;

 .my-component {
   padding: 8px;
   margin-top: 40px;
   height: 80px;
 }

and leads to export of following values to JS:

{
    "unit": "8px",
    "footer-height": "40px",
    "component-height": "80px",
    ...
}

Other computations and @value

postcss-calc and postcss-color-function are known to work inside @value as they traverse media queries. Experience with other plugins may differ if they ignore media queries.

Extracting values for programmatic use

This plugin provides to postcss a custom messages object with type: 'values'. The values property of that object will contain all the extracted values with all substitution performed (i.e. for values that reference other values).

See modules-values-extract for an example of how this can be used.

Environment

Node.js 6.5 or above is recomended.

License

ISC

With thanks

Code is mostly taken from postcss-modules-values by Glen Maddern, Mark Dalgleish and other contributors.