Cache-busting in Eleventy: a simpler way with Sass

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.