Should I upgrade to Eleventy 2.0?

13 Mar 2023

6 min read

Eleventy 2.0 was released at the beginning of February. Is it worthwhile to upgrade? Is it painful to upgrade?

What is new?

The headline improvements are faster building and a more responsive dev mode experience. A new dev server was built to replace Browsersync.

Tests on a sample 500 page site against v1.0.2 show the following improvements for build times for each of the template lanaguages:

• Liquid: 18.18% faster
• Nunjucks: 17.74% faster
• Markdown (with Liquid): 17.95% faster
• JavaScript (11ty.js): 8.33% faster

There also has been a conscious effort to reduce dependencies. Total dependencies have shrunk by 32%. This gives you quicker installation, and will make the project more reliable and stable going forward.

There are plenty of other improvements that may benefit you also. You can read the release notes for the full details.

Also, there are some important new plugins, you can use this with version 1 too AFAIK:

• The WebC plugin brings single-file web components as a first class citizen to Eleventy.
• The Eleventy Edge plugin introduces a shortcode to add dynamic content as edge functions to enable server-esque functionality.

How to upgrade

There are some breaking changes for version 2, so you may need to make some modifications to your configuration. There is an upgrade helper plugin, eleventy-upgrade-help, to identify issues.

First, you will need to upgrade the eleventy NPM package.

npm install @11ty/eleventy@2

Then, install the helper plugin:

npm install @11ty/eleventy-upgrade-help@2

Update your eleventy config temporarily to use the helper plugin:

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

module.exports = function(eleventyConfig) {
	//other statements

  // It’s important that UpgradeHelper is the LAST addPlugin() call.
  eleventyConfig.addPlugin(UpgradeHelper);
};

Run your usual build command such as npm run build and pay attention to the output. You will notice a lot of logged messages prepended with [@11ty/eleventy-upgrade-help], some of them get buried with the build messages, so you will need to scroll through them from top to bottom. It will tell you if you passed or failed some tests. Here is a sample of my output.

I had no issues. Everything seemed to work off the bat. This made me suspicious!

I reviewed the release notes to see if there was anything I should consider changing. I misunderstood a change with regard to file watching (eleventyConfig.watchIgnores) that led to me making an unneccessary change to my config. I did a diff of my website and noticed that my draft posts were making into my production build. It took me about 30 mins to realise that I introduced this by changing my config! I reversed that change and everything worked as expected.

How is version 2?

My build times decreased by the expected amount, somewhere between 10% and 20%.

Adding the --ignore-initial flag to my dev mode command cut out a significant delay up front to be able to actively work on my website. However, I have skipped this for now, because I haven’t been able to realise the benefit of the smarter incremental builds, so I need the initial build to happen. This is the same as before – a change in my custom posts collection does not trigger a rebuild of the paginated pages for my blog. I will need to review this.

The live reload is generally faster. Using the emulated passthrough copy speeds up page reloads when there are changes of the passthrough files.

Recommended?

I would recommened upgrading to version 2. It was a smooth process for me. The improvments in the dev mode experience is a good quality of life improvement. As time goes by, I might appreciate more of the changes.

Tagged

• eleventy