Skip to content

5t3ph/eleventy-plugin-lightningcss

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

9 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Eleventy Plugin: LightningCSS

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!

Features

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:

Usage

Install the plugin package:

npm install @11tyrocks/eleventy-plugin-lightningcss

Then, 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);
};

⚠️ Important: The files will end up in 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.

Config Options

Base options

Option Type Default
importPrefix string '_'
nesting boolean true
customMedia boolean true
minify boolean true
sourceMap boolean false
visitors array []
customAtRules object {}

Bundling Import Prefix

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.

Extend LightningCSS with custom transforms

Example: Support mixins and static variables

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],
  });
};

How does it work?

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.