This part has two steps, installing the plugin and adding the plugin to your site. You can do these in either order.
npm install @11ty/eleventy-upgrade-help
And then in .eleventy.js
const UpgradeHelper = require("@11ty/eleventy-upgrade-help");
module.exports = function(eleventyConfig) {
eleventyConfig.addPlugin(UpgradeHelper);
};
I started up the first few sites after installing the plugin to make sure the plugin didn’t cause any issues, and it didn’t.
Initially when I tried npm update @11ty/eleventy
the update didn’t happen. I solved this by manually updating the version number in package.json but there’s also probably a way to do it via the command line (adding @latest? maybe?).
You may not need this step but if you do, update the Eleventy version in package.json
"@11ty/eleventy": "^1.0.0",
And then hold your breath and update…
npm update @11ty/eleventy
All of my projects but one had some additional dependency updates, and all of those were straightforward and fine.
At this point when you hold your breath and test your site, the upgrade helper will give you guidance on any issues in your site in your terminal.
[@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
I was already using slugify
on most of my sites and I don’t use liquid or deep data merge, so I figured I wouldn’t encounter too many issues. As it turns out, this post was a good test for slugify
, which I was not previously using here.
Once I added this post the upgrade helper fired this message:
'Upgrading to Eleventy 1.0.0'
Expected values to be strictly equal:
+ actual - expected
+ 'upgrading-to-eleventy-1.0.0'
- 'upgrading-to-eleventy-1-0-0'
Decision time! I could update the site to use {{ title | slugify }}
instead of {{ title | slug }}
for permalinks, which would change the output to drop the special characters (in this case the periods) and replace them with dashes. Or I could just leave it as is.
Miraculously I don’t have any other posts with special characters in the title. This made it an easy choice to update all my permalink instances from slug
to slugify
without having the additional step of setting up redirects for the changing urls.
The permalink change looks like this…
"permalink": "/notes/{{ title | slugify }}/index.html"
The showstopper issue was that one of my site’s builds was failing at Netlify. This is the kind of debugging scenario mentioned earlier that I live in fear of.
12:57:43 PM: > NODE_ENV=production eleventy
12:57:43 PM: Eleventy requires Node 12. You will need to upgrade Node to use Eleventy!
OK, but I’m using 15.3.0 locally, so I’m not sure what to make of that. Fortunately it was the Eleventy community to rescue by way of a post by Sean McPherson on the same issue.
Should you encounter this issue, the fix is to add an environment variable to your Netlify deploy settings that specifies a Node version.
Key: NODE_VERSION
Value: 16.13.2
After adding the environment variable the site deployed!
Update: Maël Brunet offered a helpful tip via Twitter, pointing out that using a .nvmrc
file to store the Node version should have the same effect. I’m not using Node Version Manager (nvm), but you can create the file manually and Netlify, or presumably any host, will read the file.
To test it out I deleted the environment variable at Netlify and created file named .nvmrc
at the root of my project. In the file I added the version number like so…
16.13.2
It worked as expected! Christopher Kirk-Nielsen also suggests checking to see if you already have a .nvmrc
file that needs to be updated. Even if you didn’t create a file you might be using a starter project that included one.
Regardless of which approach you use, be sure to check the recommended latest version, which might be different than my example.
You may encounter issues I didn’t depending on your set-up. If that’s the case I wish you luck and hope your debugging skills are better than mine! Either way, happy upgrading.