Lessons Learned: Moving Eleventy from CommonJS to ESM in 2024

By Zach Leatherman

In 2024, the web development community saw a significant shift in the way JavaScript modules were being handled. With the introduction of ECMAScript modules (ESM), developers were able to take advantage of a more modern, standardized approach to module handling in JavaScript. As a result, many popular libraries and frameworks began the process of migrating from CommonJS to ESM, including the static site generator Eleventy.

As the lead developer of Eleventy, I oversaw the transition from CommonJS to ESM and learned several valuable lessons along the way. In this article, I hope to share some of those lessons with you, as well as provide insight into the process of moving a large codebase to the new module system.

Lesson 1: Embracing the Benefits of ESM

One of the first lessons I learned was the need to fully embrace the benefits of ESM. With ESM, we were able to take advantage of features such as named exports, which allowed for more fine-grained control over the modules we were working with. Additionally, the ability to import modules asynchronously with dynamic imports proved to be a game-changer for Eleventy, as it allowed us to improve performance and reduce the overall complexity of the codebase.

Lesson 2: Understanding the Limitations

Another important lesson was understanding the limitations of ESM, particularly in the context of legacy code and third-party dependencies. We encountered issues with certain libraries and packages that were still using CommonJS, which required us to find workarounds and adapt our migration strategy accordingly. It became clear that while ESM offered a more modern and standardized approach to module handling, there were still challenges when dealing with existing code that relied on CommonJS.

Lesson 3: Communicating with the Community

Finally, I learned the importance of communicating with the Eleventy community throughout the migration process. By keeping our users informed and soliciting feedback, we were able to address potential issues and ensure a smooth transition for everyone involved. This open and transparent approach not only helped us identify potential pitfalls early on, but also fostered a sense of collaboration and support within the community.

Ultimately, the process of moving Eleventy from CommonJS to ESM was a challenging but rewarding experience. By embracing the benefits of ESM, understanding its limitations, and communicating effectively with the community, we were able to successfully transition Eleventy to the new module system in 2024. I hope that the lessons I’ve shared in this article will prove valuable to other developers who are considering a similar migration for their own projects.