Process CSS in Eleventy (11ty) with LightningCSS to minify, prefix, and add future CSS support.
Also respects either your package.json browserslist or a .browserslistrc, otherwise the default targets are > 0.2% and not dead.
Review LightningCSS docs to learn more about what future CSS features are supported via syntax lowering, including color functions, media query ranges, logical properties, and more.
Note Requires Eleventy v2 - review upgrade considerations if applying to an existing project.
If you want Sass support as well, use my Sass + LightningCSS plugin instead!
LightningCSS minifies, prefixes, and enables transpiling based on your browserslist (or the included default) to gain future-CSS support today, with graceful upgrading as browser support improves.
It includes enables the following LightningCSS flags by default:
- bundling - enables including other files via the
@importsyntax - nesting
- minify
- custom media queries
Install the plugin package:
npm install @11tyrocks/eleventy-plugin-lightningcssThen, include it in your .eleventy.js config file:
const lightningCSS = require("@11tyrocks/eleventy-plugin-lightningcss");
module.exports = (eleventyConfig) => {
// If you already have a config, add just the following line
eleventyConfig.addPlugin(lightningCSS);
};collections.all and appear in places like RSS feeds where you may be using the "all" collection. To prevent that, a temporary workaround is to create a directory data file to exclude your Sass files.
Place the following in the directory containing your Sass files. As an example, for a directory called css the file would be called css/css.json:
{
"eleventyExcludeFromCollections": true
}Then, write your CSS using any organization pattern you like as long as it lives within your defined Eleventy input directory.
Note If you are already using PostCSS or Parcel, you will be doubling efforts with this plugin and should not add it.
| Option | Type | Default |
|---|---|---|
| importPrefix | string | '_' |
| nesting | boolean | true |
| customMedia | boolean | true |
| minify | boolean | true |
| sourceMap | boolean | false |
| visitors | array | [] |
| customAtRules | object | {} |
The plugin defaults to setting up 11ty to ignore CSS filenames prefixed with _ (configure with importPrefix) so that those files do not end up as separate stylesheets in your final build. That way you can signify which CSS files you are including via the @import syntax.
- Pass an array to
visitorsto include your own custom transform functions. - Pass an object to
customAtRulesto support your own at-rules
Expand to see how to configure mixins and static variables as custom at-rules using the LightningCSS docs examples for unknown and custom at-rules.
Support mixins and static variables
let declared = new Map();
let mixins = new Map();
const rules = {
Rule: {
unknown(rule) {
declared.set(rule.name, rule.prelude);
return [];
},
custom: {
mixin(rule) {
mixins.set(rule.prelude.value, rule.body.value);
return [];
},
apply(rule) {
return mixins.get(rule.prelude.value);
},
},
},
};
const tokens = {
Token: {
"at-keyword"(token) {
return declared.get(token.value);
},
},
};
const atRules = {
mixin: {
prelude: "<custom-ident>",
body: "style-block",
},
apply: {
prelude: "<custom-ident>",
},
};
module.exports = (eleventyConfig) => {
eleventyConfig.addPlugin(lightningCSS, {
customAtRules: atRules,
visitors: [rules, tokens],
});
};This plugin uses Eleventy's addTemplateFormats and addExtension features to essentiallly recognize CSS as a first-class templating language, and add custom processing. Since it makes CSS into a templating language, changes are applied during local development hot-reloading without a delay or requiring a manual browser refresh.
![Terminal output of running yarn serve: $ npx @11ty/eleventy --serve --incremental [11ty] Writing _site/src/index.html from ./src/index.html (liquid) [11ty] Writing _site/src/css/styles.css from ./src/css/styles.css [11ty] Wrote 2 files in 0.10 seconds (v2.0.1) [11ty] Watching… [11ty] Server at http://localhost:8080/ [11ty] File changed: src/css/_partial.css [11ty] Wrote 0 files (skipped 2) in 0.01 seconds (v2.0.1) [11ty] Watching…](https://private-user-images.githubusercontent.com/19352442/238495076-4b32bd98-c725-40d8-8492-7e6e86284e97.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjIxMjI0MTUsIm5iZiI6MTcyMjEyMjExNSwicGF0aCI6Ii8xOTM1MjQ0Mi8yMzg0OTUwNzYtNGIzMmJkOTgtYzcyNS00MGQ4LTg0OTItN2U2ZTg2Mjg0ZTk3LnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNDA3MjclMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjQwNzI3VDIzMTUxNVomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPWEzN2Y3ODNmZDUxNDQzNjMyMDYyOGIyMWU0MzUwZDlmODlhMWJjODMzMTczZTk1YTdlZmY4NThjNDg4OGFmYmMmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JmFjdG9yX2lkPTAma2V5X2lkPTAmcmVwb19pZD0wIn0.RYnoHKl6sT1dwdi9x34AG2wAKEcySaD0Qeuk0jc7Dfg)
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent