postcss-lightningcss

This PostCSS plugin uses lightningcss to compile and minify your CSS.
lightningcss
is more than a minifier as it can replace several PostCSS plugins such as autoprefixer
.
You can find the complete list of features in the package's documentation and the list of plugins it can replace below.
Install
yarn add -D postcss-lightningcss
Usage
const postcss = require("postcss");
const postcssLightningcss = require("postcss-lightningcss");
postcss([postcssLightningcss()]).process(
YOUR_CSS
);
Options
const postcssLightningcss = require("postcss-lightningcss");
postcssLightningcss({
browsers: ">= .25%",
cssModules: /\.module\.css/,
cssModulesJSON(cssFileName: string, json: object, outputFileName: string): {},
lightningcssOptions: {
minify: true,
sourceMap: true,
cssModules: false,
targets: {
safari: (13 << 16) | (2 << 8),
},
drafts: {
nesting: false,
},
},
});
The detailed list of lightningcssOptions
can be found here
CSS Modules
When transforming CSS Modules, class names get changed.
To get the mapping of the class names, you can specify a cssModulesJSON
function like the following:
const path = require("path");
const fs = require("fs");
postcssLightningcss({
cssModules: /\.module\.css/,
cssModulesJSON(cssFileName, json, outputFileName) {
const cssName = path.basename(cssFileName, ".css");
const jsonFileName = path.resolve("./build/" + cssName + ".json");
fs.writeFileSync(jsonFileName, JSON.stringify(json));
},
});
You may also combine this with custom naming patterns:
postcssLightningcss({
cssModulesJSON(cssFileName, json, outputFileName) {
},
lightningcssOptions: {
cssModules: {
pattern: "my-company-[name]-[hash]-[local]",
},
},
});
Note that using a custom pattern cannot be used at the same time as using a RegEx to conditionally enable CSS modules because the cssModules
option within lightningcssOptions
takes precedence over the plugin's cssModules
option
About source maps
Source maps will pass through lightningcss
.
But many mappings will be lost in translation; lightningcss
creates only a source map for selectors.
Mappings for properties cannot be re-created after this transformation.
PostCSS plugins that you can remove if you have lightningcss
This list is not exhaustive. If you have a doubt, have a look at the Lightning CSS Playground
The rows marked as "Depends on browser config" will convert your CSS only if:
- You set the
browsers
or lightningcssOptions.targets
options
- one of the target browsers doesn't support the feature
autoprefixer | Depends on browser config |
postcss-clamp | Depends on browser config |
postcss-color-hex-alpha | Depends on browser config |
postcss-color-hsl | Depends on browser config |
postcss-color-rgb | Depends on browser config |
postcss-color-function | Depends on browser config |
postcss-color-rebeccapurple | Depends on browser config |
postcss-custom-media | lightningcssOptions.drafts.customMedia |
postcss-double-position-gradients | Depends on browser config |
postcss-hwb-function | Depends on browser config |
postcss-lab-function | Depends on browser config |
postcss-logical | Depends on browser config (1) |
postcss-media-minmax | Depends on browser config |
postcss-multi-value-display | Depends on browser config |
postcss-nesting | lightningcssOptions.drafts.nesting |
postcss-normalize-display-values | Depends on browser config |
postcss-oklab-function | Depends on browser config |
postcss-overflow-shorthand | Depends on browser config |
postcss-place | Depends on browser config |
postcss-progressive-custom-properties | Depends on browser config (2) |
lightningcss
doesn't support the logical
shorthand keyword as its syntax is likely to change
- Progressive custom properties work only if the properties don't contain properties themselves:
lab(29.2345% 39.3825 20.0664)
has a proper fallback
oklch(40% 0.234 0.39 / var(--opacity-50))
will not have a fallback
License
MIT