Should I upgrade to Eleventy 2.0?

Eleventy 2.0 was released at the beginning of February. Is it worthwhile 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 an conscious reduction in dependencies, a decrease by 32%. This gives you a 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.

[@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.

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.