With Eleventy 1.0 coming soon, I thought I'd take a look at the experience of upgrading an existing implementation to the latest version. As I've warned, Eleventy 1.0 is still in beta so the details may change, but I figured it was safe to give it a try on my own site (the very place you're reading this post). Eleventy is shipping a tool to help with that process, and I cover that a bit later, but me being who I am I just went ahead and Leroy Jenkins the process.

After upgrading Eleventy to the 1.0 beta (npm i @11ty/eleventy@beta), I fired up my local copy of this site and... bam! It crashed. Luckily though the error was nice and clear:

Error about unknown filter

This error makes me very, very happy. What is it? The LiquidJS template language (the primary one I use for this site, but not exclusively) is a great project, but for some reason has a default behavior that I find insane. When using a filter that doesn't exist, the default behaviour is for Liquid to ignore it. So your coworker tells you to use the cat filter in certain blocks, like so:

Hello {{ name | cat }}

But it turns out you misheard them and they meant to say kitten filter. By default, Liquid sees the undefined filter and just does nothing. I am sure there is a valid reason for this, and it absolutely makes sense to make being strict about this an option, but I cannot fathom why it would default to not being strict. Turns out, I had about 5-6 cases of a filter that wasn't defined that was just silently ignored.

So in Eleventy 1.0, they simply set the default Liquid option to enforce strict filters. I really like this change. It took me maybe five minutes to fix the various filters in my site that weren't working (I literally just got rid of em, I didn't need them).

Woot! Ok, but then I had another problem:

illegal filename error

The line in question looked like so:


{% include footer %}

This issue is covered in the Eleventy Liquid docs here:

Warning about includes

The solution was to just add single quotes:


{% include 'footer' %}

I had maybe ten of these around my site, but it was also a five minute fix or so.

Ok, so at this point, I was able to get things running locally just fine. As an FYI, and I don't think it would have mattered but it's nice to know, I run Eleventy locally via the Netlify CLI and Netlify Dev, and nothing in that process seemed to intefere with Eleventy 1.0. Again, I didn't expect there would be an issue, but it's nice to know. At this point, I decided to look at the helper plugin.

First off, I was a bit surprised the 'helper' was a plugin, as I would have imagined some kind of local script you run that looks at your code, but running in context with your site itself as a plugin makes sense too. As a regular Eleventy plugin, you simply install it and then add support to your .eleventy.js. While I don't think it matters if I keep it around forever, I added some helpful comments like so:

// remove me
const UpgradeHelper = require("@11ty/eleventy-upgrade-help");

// later in my file

//remove me
eleventyConfig.addPlugin(UpgradeHelper);

I guarantee you I'm going to forget and look into removing it sometime around Eleventy 2.0. The plugin fdocuses on a few particular items. While you can get details at the docs, it checks for:

  • Use of the slug filter that should now be slugify.
  • Warnings about deep data merge not being turned on.
  • Liquid changes (would have helped me with the stuff above!)
  • And a change to non-root .gitignore stuff (doesn't apply to me)

When I ran Eleventy, I saw this (switching from screenshots to a text copy so it's hopefully easy to read):

[@11ty/eleventy-upgrade-help] PASSED `slug` to `slugify` filter
[@11ty/eleventy-upgrade-help] WARNING eleventyConfig.setDataDeepMerge(true) is the new 1.0 default. Revert with eleventyConfig.setDataDeepMerge(false);
[@11ty/eleventy-upgrade-help] WARNING The liquidjs `strictFilters` option default (in Eleventy) changed from false to true. Revert with `eleventyConfig.setLiquidOptions({ strictFilters: false })`.
[@11ty/eleventy-upgrade-help] WARNING The liquidjs `dynamicPartials` option default changed from false to true. Functionally this means `include` statements require quotes now. Revert with `eleventyConfig.setLiquidOptions({ dynamicPartials: false })`.
[@11ty/eleventy-upgrade-help] PASSED input directory .gitignore check

Nice, simple, and direct. You can tweak what the plugin checks if you want, but I'd probably leave it at the default.

For now, I'm not running the 1.0 changes in production, just locally. As this site is a blog that's pretty easy to do - I only commit my new posts. With me assuming we'll have a formal 1.0 release on the 11th, I'll wait till then, test again, and commit. Enjoy!