Eleventy Barebones

Github Repository

If you want to generate static sites and haven't tried Eleventy (11ty), you are missing out! I'm a big fan of both its simplicity and its configurability. But because of that simplicity, 11ty leaves a lot of choices up to the developer, like how to handle assets like JavaScript and CSS.

If you are doing anything more than creating basic HTML and CSS, like writing ES6 JavaScript or using SCSS, you need some way of converting that code into a browser-compatible version. I've searched for a perfect 'barebones' setup in 11ty for a long time, and never quite found the perfect boilerplate for me. So I've created my own setup with an asset pipeline that works exactly the way I want it to work.

My setup uses esbuild for 2 things:

1. Transpiling and Bundling JavaScript
2. Converting SCSS into CSS and minifying the result

I also take advantage of esbuild's ability to add hashed file names in order to prevent caching issues. To me, this is an essential component of any static site generator. In my current job, I'm constantly pushing small CSS or JS changes to client sites. And when caching gets in the way, it can prevent clients from seeing the updates as they go live.

When building for production, esbuild will add unique hash extensions to each JS and CSS file based on the contents: app.MAEY36TZ.js. During that build process, I make esbuild create a hash.json file that looks like this:

        
{
    "src/assets/js/app.js": "dist/assets/js/app.MAEY36TZ.js",
    "src/assets/styles/app.scss": "dist/assets/styles/app.X6PSTJRV.css"
}
        
    

Then, using a custom 11ty filter, I can reference those hashed file names:

        
<script src="{{ 'src/assets/js/app.js' | hash }}"></script>
        
    

I think this setup is a lot simpler than some of the other solutions I've found online, like creating a custom template language to handle JS or SCSS. Solutions like these can work, and I like how they work within the build process of 11ty, but I think they lose a lot of the features of build tools like esbuild, such as the hashed file names.

If you want to see the entire setup, feel free to copy or fork my repository here.