v3.0.0 Upgrade Plugin

[zachleat]

https://github.com/11ty/eleventy-upgrade-help

[zachleat]

Breaking changes list: https://github.com/11ty/eleventy/issues?q=milestone%3A%22Eleventy+3.0.0%22+is%3Aclosed+label%3Abreaking-change

• Throw if --config is specified but the file is not found #3373
• Remove htmlOutputSuffix Common Pitfall when input and output directories match. #3327
• Breaking: Aliased template syntax must be explicitly listed in template formats #3302
• Cleanup for --formats, templateFormats config, and setTemplateFormats addTemplateFormats configuration API methods #3255
• Official Eleventy v3.0 Template Language plugins: ✅ Handlebars, ✅Mustache, ✅ EJS, ✅ Haml, 👀 Pug #3124 Move some of the default plugins into plugin land #1103 Eleventy v3.0 Template Syntax plugin: Pug #3081
• Node minimum update to v18 #3110
• compileOptions.permalink default changed from true to "raw" for Custom Template Syntaxes #2780
• Breaking: js-yaml bump from v3 to v4 for better error messaging for tabs versus spaces in YAML front matter #2126

[zachleat]

• Edge and Serverless plugins Update Serverless and Edge docs with guidance about 3.0 #3129
• require("@11ty/eleventy"); https://www.11ty.dev/blog/canary-eleventy-v3/#how-to-require(andquot;@11ty/eleventyandquot;)-in-commonjs

[zachleat]

Future-friendly error message when you try to require("@11ty/eleventy") in 3.0.0-alpha.18 or newer. This will not be shown when using --experimental-require-module or when Node.js enables require of synchronous ESM by default.

> @11ty/[email protected] build
> npx @11ty/eleventy --quiet

[11ty] 1. Error in your Eleventy config file 'eleventy.config.js'. (via EleventyConfigError)
[11ty] 2. Eleventy cannot be loaded via `require("@11ty/eleventy")` in 3.0 and newer. Instead, you have a few options:
[11ty]    1. (Easiest) Change the `require` to use a dynamic import inside of an asynchronous CommonJS configuration callback, for example:
[11ty] 
[11ty]       module.exports = async function {
[11ty]         const {EleventyRenderPlugin, EleventyI18nPlugin, EleventyHtmlBasePlugin} = await import("@11ty/eleventy");
[11ty]       }
[11ty] 
[11ty]    2. (Easier) Update the JavaScript syntax in your configuration file from CommonJS to ESM (change `require` to `import` and rename the file to have an .mjs file extension).
[11ty]    3. (More work) Change your project to use ESM-first by adding `"type": "module"` to your package.json. Any `.js` will need to be ported to use ESM syntax (or renamed to `.cjs`.)
[11ty]    4. (Short term workaround) Use the --experimental-require-module flag to enable this behavior. Read more: https://nodejs.org/api/modules.html#loading-ecmascript-modules-using-require It is possible that the newest version of Node has this enabled by default—you can try upgrading your version of Node.js.

[zachleat]

https://www.npmjs.com/package/@11ty/eleventy-upgrade-help v3.0.0 is now available on npm.

I’ve updated the demo project to use it as well: https://github.com/11ty/demo-eleventy-upgrade-help/

There are a few small improvements to core that will ship with 3.0.0-alpha.18 to improve error messaging on ESM and retired Serverless/Edge plugins and #3373 but everything else should work as-is with the newest published canary alpha.