Should I upgrade to Eleventy 2.0?

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:

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:

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.

Shell
npm install @11ty/eleventy@2

Then, install the helper plugin:

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

Update your eleventy config temporarily to use the helper plugin:

Javascript
//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.

terminal

npm run build

> ELEVENTY_ENV=production npx @11ty/eleventy

[@11ty/eleventy-upgrade-help] —
[@11ty/eleventy-upgrade-help] This plugin will help you migrate from 1.0 to 2.0.
[@11ty/eleventy-upgrade-help] If you are migrating from 0.x, downgrade to the 1.0 version of this plugin!
[@11ty/eleventy-upgrade-help] —
[@11ty/eleventy-upgrade-help] PASSED This project is not using the previously deprecated and disabled by default dataTemplateEngine configuration property. Read more at https://www.11ty.dev/docs/data-preprocessing/
[@11ty/eleventy-upgrade-help] PASSED This project is not using the --passthroughall command line flag. Read more at https://www.11ty.dev/docs/copy/#passthrough-everything
[@11ty/eleventy-upgrade-help] NOTICE The liquidjs dependency was updated from 9.x to 10.x. This should not require action, but you can read the full release notes: https://github.com/harttle/liquidjs/releases/tag/v10.0.0
[@11ty/eleventy-upgrade-help] NOTICE Markdown’s indented code blocks have been disabled by default in 2.0. Unfortunately, this plugin does NOT currently test whether this change affects your content. You can re-enable this feature using eleventyConfig.amendLibrary("md", mdLib => mdLib.enable("code")). Read more: https://www.11ty.dev/docs/languages/markdown/#indented-code-blocks
[@11ty/eleventy-upgrade-help] PASSED Eleventy has a new default ignore pattern of **/node_modules/** (previously: node_modules/**). Read more, including how to revert this behavior: https://www.11ty.dev/docs/ignores/#node_modules. This does not appear to affect your project, as you have no nested node_modules folders!
[@11ty/eleventy-upgrade-help] PASSED This project is using Node 14 or newer!
[@11ty/eleventy-upgrade-help] PASSED This project is not using the Render plugin. If it did, I’d remind you that the renderTemplate shortcode behavior changed slightly in 2.0. But you don’t need to worry about it here. Read more: https://github.com/11ty/eleventy/issues/2310
[@11ty/eleventy-upgrade-help] NOTICE eleventyConfig.ignores are no longer re-used for the file watcher during --watch and --serve. If you’d like files to be ignored by the file watcher (to avoid triggering new builds), use the new dedicated eleventyConfig.watchIgnores API instead. Read more: https://www.11ty.dev/docs/watch-serve/#ignore-watching-files
[@11ty/eleventy-upgrade-help] PASSED Browsersync is no longer the default Development Server in Eleventy. This project doesn’t seem to be making use of any custom Browsersync options, so it’s unlikely to be affected! Learn more: https://www.11ty.dev/docs/dev-server/
[@11ty/eleventy-upgrade-help] PASSED Global data files with one or more dots in the file name are stored differently in the data cascade in Eleventy 2.0. For example, a.b.json stores as 'a.b': value instead of a: { b: value }. This project has no affected data file paths. Read more: https://github.com/11ty/eleventy/pull/1912

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.

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