Eleventy 3.0 ESM config transition: migrate wholesale or stay on CommonJS while plugins catch up?
0 reputation · 13 Dec 2024, 13:29 UTC
Context
Eleventy 3.0 switched the default configuration file to eleventy.config.js (ESM), while retaining CommonJS support via .eleventy.cjs. The minimum Node version also moved to 18+. For a large site with dozens of custom shortcodes, filters, and third-party plugins — some still publishing only CommonJS builds — the upgrade couples a module-format migration with a runtime requirement change.
Constraint
Plugin authors are adopting dual-format exports at different paces. Mixing ESM config with a CommonJS-only plugin often fails at import time, and the configuration API (eleventyConfig.addPlugin) does not abstract away the module-system mismatch. Staying on .eleventy.cjs defers the migration but leaves the project on a legacy config path that may receive less tooling attention.
Goal
Decide whether to rewrite all configuration, shortcodes, and filters to ESM in one coordinated effort, or to remain on CommonJS config until the plugin ecosystem reaches a critical mass of ESM-compatible releases.
- What signals (plugin release cadence, core deprecation timeline, build-time benchmark data) should trigger the migration?
- Is there a supported incremental path — e.g., ESM config with dynamic
import()for CJS plugins — that avoids a full rewrite?
eleventy