Jumping in

I took the plunge today and upgraded my site adamjolicoeur.com to the Eleventy v3.0 beta. I've been following along with the progress of v3 since it was announced and, with the latest news that Eleventy will be joining the team behind Font Awesome, felt that this was a good time to take the plunge.

Starting the process

What better place to start than 11ty.com? Scrolling towards the bottom, I found the link in the "News from the blog" section, which took me to the blog post, which I then used to get to the GitHub page specific to the Eleventy v3.0.0-beta.1 release notes. From there, I followed the instructions of installing the beta and then the migration plugin.

npm install @11ty/eleventy@beta
npm install @11ty/eleventy-upgrade-help@3

The instructions in the eleventy-upgrade-help plugin state to install @11ty/eleventy@3 yet there is no @3 version. Replace @3 with @beta to use the beta release.

Upgrading

After installing the required dependencies, a simple update to my .eleventy.js file was needed:

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

module.exports = function(eleventyConfig) {
  // If you have other `addPlugin` calls, UpgradeHelper should be listed last.
  eleventyConfig.addPlugin(UpgradeHelper);
};

Upgrade Plugin Placement

In my case, I added eleventyConfig.addPlugin(UpgradeHelper); above the eleventyConfig.setBrowserSyncConfig({ section, which contains my local browser configuration and is followed by library configuration settings.

After those updates were made, I proceeded to run both npm run build and npm start in order to build the initial files before starting up my local development server. (The instructions stated to run npm build but, knowing how my environment is configured, I knew that both prompts were needed.)

On your mark, get set, migrate!

Now that my environment was configured, it was time to kick off the migration from v2 to v3. I quickly realized though, that when updating .eleventy.js, that I had placed the UpgradeHelper plugin in the wrong area of the file. If done correctly, you should see the following in your prompt:

Unfortunately, I received this:

Realizing that I was not getting to the UpgradeHelper while also receiving a new v3 error, I rechecked my configuration file (see upgrade plugin placement) and added a new line to bypass this error: eleventyConfig.setFreezeReservedData(false);.

Plugin Output

If you're seeing output similar to what is shown in the screenshot above, you're on the right path! For me, the most important output was seeing [11ty/eleventy-upgrade-help] This plugin is intended for temporary use: once you’re satisfied please remove this plugin from your project.. This told me that the plugin had been run and that any issues would (or should) be caught and thrown.

Additional output messages

[11ty/eleventy-upgrade-help] PASSED All of your project’s .html output files (×0) are using <meta name="generator" content="Eleventy …">

Informs the reader that all files are using the correct <meta> information for Eleventy.

[11ty/eleventy-upgrade-help] PASSED Eleventy will fail with an error when you point --config to a configuration file that does not exist. You are not using --config —so don’t worry about it! Read more: https://github.com/11ty/eleventy/issues/3373

Let me know that my configuration file is in good shape while also telling me what to avoid using.

[11ty/eleventy-upgrade-help] PASSED You aren’t using --formats= or  --formats='' but if you were you should know that these are now empty template format sets. In previous versions, they were aliased to "*". Read more: https://github.com/11ty/eleventy/issues/3255

Informing me that I do not have any empty format sets.

[11ty/eleventy-upgrade-help] PASSED No {pug,ejs,haml,mustache,handlebars} templates were found in this project. If you were, you would have needed to install plugins for these: https://github.com/11ty/eleventy-plugin-template-languages. Learn more: https://github.com/11ty/eleventy/issues/3124

The upgrader checked for any files other than Markdown (.md) or (/html), which would require an additional plugin. None were found, so that plugin is not needed.

These are only a few of the messages that were given by the upgrade plugin - each one was informational and provided references to GitHub issues.

Final thoughts

The upgrade from Eleventy v2 to Eleventy v3 was fairly straightforward and simple to incorporate into my site. There was a noticeable improvement in build time and responsiveness in the process. As part of the completed build, the final line was as follows: Copied 150 Wrote 27 files in 0.11 seconds (v3.0.0-beta.1). Not bad at all!

Once the final release drops, I'll be sure to go full v3. My site builds cleanly, fast, and I'll be able to simplify things moving forward.

If you have any questions, feel free to drop them in the comments below and I'll answer as best I can! Thanks for reading!