Any guidance for plugin authors on adding ESM support for Eleventy 3?

[gfscott]

I'm looking forward to Eleventy 3.0 and the (optional) switch to ESM. I think I've got a handle on it as an end user of Eleventy — but I'm wondering how best to plan ahead and support that transition as a plugin author. Questions like:

• How best to maintain backward compatibility?
  • Can I also adopt ESM incrementally with .cjs and then transition back to .js over time? I'm unsure what the playbook is here.
• Should I be switching to hybrid packages (that include both CJS and ESM modules)? Any recommendations or preferred tooling or methodology for that?
  • If I'm adopting a build step for hybrid packaging anyway, should I consider switching to TypeScript?

I'm just trying to get these questions straight in my own head, and I suspect others might be too! If anyone has thoughts on how best to tackle this, I'm all ears.

[zachleat]

• Existing plugins will work fine as-is in CommonJS projects and ESM projects with a .cjs config file.
• Existing plugins will work fine as-is in ESM projects (you can import a CommonJS package as-is in Node.js)
• If you upgrade your plugin to use ESM, this will be a breaking change (make sure you bump to a new major version when publishing) for CommonJS config files (but ESM config files will work without changes)—they’ll need to use await import() instead of require() for the plugin. This is the exact same as what we recommend for core Eleventy now (which exposes a few now-ESM plugins): https://www.11ty.dev/blog/canary-eleventy-v3/#how-to-require(@11ty/eleventy)-in-commonjs

I wouldn’t double-publish any plugins as ESM/CJS hybrids if I were you, it just seems like a headache moving forward (let’s move to ESM-only, slowly)

One more point I would note: Eleventy plugins written in ESM could be made to work in Eleventy v2 using await import() in an async event handler (e.g. https://www.11ty.dev/docs/events/) but I think that we should probably just encourage folks to use Eleventy v3 for ESM plugins moving forward to keep the installation instructions from ballooning to an extra layer of complexity.

[gfscott]

This is all good to know, thanks! 🙏🏻 (Especially not having to do any hybrid packaging, I was kind of dreading that 😬)