Eleventy 3.0 ESM config transition: migrate wholesale or stay on CommonJS while plugins catch up?

You should remain on .eleventy.cjs until you have a specific requirement for ESM-only features or top-level await.

While Eleventy 3.0 defaults to ESM via eleventy.config.js, the core team has not announced a deprecation timeline for the CommonJS path. Since the move to Node 18+ is mandatory for both formats, staying on CommonJS does not bypass the runtime upgrade, and a wholesale rewrite of a large site's custom shortcodes and filters carries high risk for low immediate gain.

The Incremental Migration Path

You do not need to rewrite everything at once. If you choose to move to an ESM config, you can use dynamic import() to handle CommonJS-only plugins. This allows you to migrate the configuration structure now while keeping legacy logic in place.

// Example of an ESM eleventy.config.js handling CJS plugins
export default async function(eleventyConfig) {
  // Standard ESM-compatible plugin
  eleventyConfig.addPlugin(someEsmPlugin());

  // CommonJS-only plugin via dynamic import
  const cjsPlugin = await import('cjs-only-plugin');
  eleventyConfig.addPlugin(cjsPlugin.default || cjsPlugin);
}

Signals to Trigger a Wholesale Migration

A full migration is only justified when one or more of the following signals appear:

• Tooling Friction: If your CI/CD pipeline, linters, or IDE plugins begin to fail or lose support for .cjs files specifically.
• Dependency Deadlocks: If you need to use top-level await in your configuration logic, which is only supported in ESM.
• Ecosystem Maturity: When the majority of your critical third-party plugins provide dual-format exports, making the dynamic import() boilerplate unnecessary.

Assumptions and Uncertainty

This analysis assumes your project relies heavily on third-party plugins that have not yet updated their exports maps. The primary uncertainty lies in the pace of the plugin ecosystem; however, historically, Eleventy maintains high compatibility for legacy configurations to avoid breaking large-scale sites.