$ node --version
v20.11.0

11ty upgrade helper

I will start by following the directions for 11ty's official upgrade helper . This starts with installing v3 of 11ty (I use the command to upgrade from v2 to v3):

$ npm install @11ty/eleventy@3

Next, I install the upgrade helper (again, this is for upgrade from v2 to v3):

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

Then we need to import and use the help. I follow the ESM instructions for adding to my configuration file-- note that export is changed from

module.exports = function (eleventyConfig) {
  ... 
  };

to

export default function (eleventyConfig) { 
  ...
  };

resulting in a format like this:

import UpgradeHelper from "@11ty/eleventy-upgrade-help";

export default function (eleventyConfig) {
  // If you have other `addPlugin` calls, it’s important that UpgradeHelper is added last.
  eleventyConfig.addPlugin(UpgradeHelper);
};

Finally, we are told to run our build command and fix the errors. I think there are A LOT of unmentioned things that can go wrong here, but... I try.

$ npm run start

... cut ...

(node:16770) Warning: To load an ES module, set "type": "module" in the package.json or use the .mjs extension.
(Use `node --trace-warnings ...` to show where the warning was created)
[11ty] Eleventy Error (CLI):
[11ty] 1. Error in your Eleventy config file '.eleventy.js'. (via EleventyConfigError)
[11ty] 2. Cannot use import statement outside a module (via SyntaxError)
[11ty] 

... cut ...

ESM and CommonJS

Prior to version 3, 11ty used CommonJS as the default/only option. It is still possible to use CommonJS, but I am going to choose ESM as the default ( more info on ESM vs CommonJs in 11ty available here ). So, The first error I get makes sense: there is a complaint about the my attempt to load the helper package using ESM syntax. As suggested, I will adjust my package.json file to set the "type" to "module" by adding a line:

"type": "module",

Changing "require" statements to "import"

Changing the "type" to "module" means that Node now expects ESM style imports instead of the "require" statements used in CommonJS. This means the statements like:

const randomPlugin = require("random-plugin");

get changed to

import randomPlugin from "random-plugin";

in your configuration file. There are likely a bunch of these statements at the top of the file.

Out of date dependencies

After making the change(s) above I was still getting errors about CommonJS style imports. I made sure that none were in my config file and decided this might be the result of out of date dependencies. I found out I did have outdated dependencies with:

$ npm outdated
Package                                Current  Wanted  Latest  Location                                            Depended by
@11ty/eleventy-img                       3.1.0   3.1.8   6.0.0  node_modules/@11ty/eleventy-img                     chrisstrelioffws-11ty
@11ty/eleventy-plugin-syntaxhighlight    4.2.0   4.2.0   5.0.0  node_modules/@11ty/eleventy-plugin-syntaxhighlight  chrisstrelioffws-11ty
@11ty/eleventy-plugin-webc              0.11.1  0.11.2  0.11.2  node_modules/@11ty/eleventy-plugin-webc             chrisstrelioffws-11ty
sass                                    1.56.0  1.83.1  1.83.1  node_modules/sass                                   chrisstrelioffws-11ty

I attempted to fix this with:

$ npm update

to see if that would help. It helped, yay! This means that updating dependencies resulted in the helper script working as intended; go figure! Next up, let's document some of the errors I encounted.

Errors I encountered...

Now that I had the basics working, I started to work through errors that came up with building. I'll document here, for myself, and maybe you?

Computed data

I am using computed data, *.11tydata.js, and the export syntax had to change from:

// CommonJS style
module.exports = {
  eleventyComputed: {
    eleventyNavigation: {
      key: (data) => data.title,
      parent: (data) => data.parent,
    },
  },
};

to

// ESM style
export default {
  eleventyComputed: {
    eleventyNavigation: {
      key: (data) => data.title,
      parent: (data) => data.parent,
    },
  },
};

Javascript functions

I use a couple of javascript functions that need to be exported. This requires the change from

// CommonJS style
// -- from https://www.11ty.dev/docs/languages/javascript/#function
module.exports = function (data) {
  return `<p>${data.name}</p>`;
};

to

// ESM style
// -- from https://www.11ty.dev/docs/languages/javascript/#function
export default function (data) {
  return `<p>${data.name}</p>`;
};

Javascript classes

I use javascript classes to do some parsing of tags. The export of the class had to be updated, like so (note the export in the final line):

// ESM style
// -- from https://www.11ty.dev/docs/languages/javascript/#classes

class Test {
  // or `async render({name}) {`
  render({ name }) {
    return `<p>${name}</p>`;
  }
}

export default Test;

Removing the helper plugin

Making changes to multiple files that had the issues cited above resulted in a working v3 upgrade of 11ty. All that's left is to uninstall the plugin and remove the related lines from the config file:

$ npm uninstall @11ty/eleventy-upgrade-help

and remove the lines

// remove import statement
import UpgradeHelper from "@11ty/eleventy-upgrade-help";

// remove addPlugin statement
eleventyConfig.addPlugin(UpgradeHelper);

That's it! I have other 11ty sites to update, so I'll be coming back to these notes. If you find any issues, drop me an email (see below).