If you use the Eleventy static site generator (SSG) and Sass to build your website, read on for some cool stuff.
Back in late 2020, I wrote three posts about how to perform “cache-busting” on an Eleventy site’s CSS, which ensures the vast majority of web browsers will reliably show your most up-to-date styling. In the end, I suggested a method that accomplished this through a combination of package.json scripting and build-time JavaScript runs. It worked, but it was somewhat of a time drag during dev mode. Besides, it’s a lot clunkier than how one can do it in Hugo via that SSG’s built-in asset pipeline, Hugo Pipes. Thus, I’ve continued to look for a better way.
Now, I’ve found it.
It comes in the form of two recently introduced Eleventy plugins by Kentaro Imai: eleventy-sass and eleventy-plugin-rev. The former provides Sass-to-CSS compilation, and the latter adds filters you can access to provide versioning-based filename changes for cache-busting.
It’s as simple as this. First, go to your Eleventy project directory and install the two plugins from npm:
npm i -D eleventy-sass eleventy-plugin-rev
Then register them in the project’s config file, usually a top-level .eleventy.js file, as in this simplified example (see the eleventy-sass documentation for more details about available options):
const pluginRev = require("eleventy-plugin-rev");
const eleventySass = require("eleventy-sass");
module.exports = function(eleventyConfig) {
eleventyConfig.addPlugin(pluginRev);
eleventyConfig.addPlugin(eleventySass, {
rev: true
});
/*
other Eleventy config as usual...
*/
}
Finally, add the following to your template for the site-wide head tag (the following assumes you have an index.scss file within src/styles/):
<link rel="stylesheet" href="{{ "/styles/index.css" | rev }}" type="text/css" />
That’s all!
Compared to my method from 2020, this requires no weird gyrations in package.json and no build-time machinations in JavaScript. It’s so much cleaner and simpler.
Now, on each run of Eleventy, the combo of eleventy-sass and eleventy-plugin-rev will create a CSS file with a hashed filename that changes every time you make a change to index.scss or any partials that index.scss might @use. (And you’ll want to @use, not @import, because the Sass-to-CSS compilation in eleventy-sass is done with Dart Sass, rather than the deprecated LibSass.)
Incidentally: in my own testing of this setup in dev mode, Eleventy’s --incremental flag keeps the dev server’s refresh functionality from calling the renamed CSS file when you alter the SCSS (and therefore cause that renaming to occur). Also, I found this to be true with both Eleventy 1.x and the still-in-development Eleventy 2.x; so I’d suggest not using --incremental if you don’t want to have to do a dev server refresh every time you make an SCSS change.
That little gripe aside, I encourage all Eleventy/Sass users to consider adopting this quick config improvement, courtesy of some neat coding by Kentaro Imai. It’s ’waaay cleaner than any other Sass-using, cache-busting solution for Eleventy that I’ve yet encountered, and you can have it up and running in just a few minutes.
Top comments (1)