ESModule use cases, a list in progress

esm_use_cases.md

ES module use cases

• Alice is writing a new library, and she is excited to use the new ES6 syntax. However, she would like to use an older but still good package she found on npm, that exports its interface using CommonJS. She does so easily after reading the NodeJS documentation on how to do this.

• Bob is updating a module for his work, and he needs to support existing CommonJS-using codebases as well as a new project that prefers to stick with ES6 for static analysis reasons. He publishes a package that exports both kinds of interfaces.

• Carol is updating her popular code coverage reporting tool for the new world. She uses the ESM loader hooks to instrument test code as it is imported so she can get code coverage reporting on par with what she has for CommonJS.

• David is writing a transpiler. He writes a custom hook that transpiles source as it's loaded from his language to JavaScript.

• Eugenia wants to abandon the CommonJS API for her existing npm package and move to a new ESM-only API.

• Hermione wants to load modules from a database and not from the filesystem. She writes a custom loader hook to do so.

• Ian wants to replace the dependencies of a module with mocks while testing. He writes a custom hook to do so.

Frances has a large application and wants to be able to gradually migrate from CJS to ESM, one file at a time, without forcing codebase-wide changes.

George, like Bob, wants to update a package to use ESM, but needs to support existing CJS-using codebases, but wants to adopt the new syntax one file at a time, without forcing changes in their own codebase and without creating a breaking (semver-major) change.

Jacqueline has a non-node application that is unable to take advantage of a node-based build system, but still wants to consume JavaScript code that is typically built in node. They are able to programmatically determine if they need a <script> or <script type="module"> without having a JavaScript parser available.

Karl is yet unable to use ESM in their own code, because their company is still unwilling to change their coding style and workflow. However, they want to use Eugenia's ESM-only package. They are able to access it with require and make use of it, both while still on an older version of node (that lacks ESM support) and after upgrading to a newer version of node (that has ESM support).

Maybe:

• Carol is updating her popular code coverage reporting tool for the new world. She can get code coverage reporting on par with what she has for CommonJS.

These are great.

• As a maintainer of a legacy project, I frequently have to update old code. As I update bits and bobs of older code, I integrate modern features and standards piece-wise. When I update one of my files, I'd like to adopt some pieces of modern ES syntax where possible (similarly to how I adopted classes or async functions), while keeping any changes I need to make local to my original update and my API unchanged.

• Alice is using an existing npm package that is written in CommonJS. She wants to use one specific function exported from its module.exports and wants to ensure she does it in a way that bundlers will understand while tree-shaking. There are clear best practices she can look up to do so.

• Robin reads the source of one of their projects and finds an import statement. They want to quickly find the file being imported. After a few steps they find the imported file in their file system.

Maybe good base questions:

• What are people doing with CommonJS in node
• What are people doing in other module ecosystems outside of node
• What do people like about using the module system in node
• What do people dislike / miss when using the module system in node

• Justin, a seasoned NodeJS developer, has no desire to use the new ES module features and wants to continue using CommonJS modules with his existing dependencies. He doesn't want his application to break or slow down beyond the standard deprecation paths in Node as he upgrades to new versions of NodeJS in his app.

• Quinn updates an app and wants to switch it from its existing CommonJS implementation to using ES modules. They can rewrite the code after reading the node docs without relying on trial-and-error or reading all READMEs (or even source) of their dependencies.

• Joe has written an ES module that leverages WASM internally for the web. The module uses import to load the compiled WASM file and everything worked fine in the browser. Joe wants to import the ES module from a server-side script and can do so without having to change the file.

• Alex is writing a universal library using both ES modules and existing CommonJS modules which she would like to build for both NodeJS and the browser.

• Geoffrey wants to rewrite CoffeeScript’s modules tests from being string comparisons to instead actually execute import and export statements. The test runner is written in CommonJS, and needs to test both transpiled CommonJS strings and transpiled ES module strings output from the new modules tests.

Okay, maybe this one is overly specific, but a real-world use case can’t hurt 😄 The generalized case of test runners that need to test both types of modules is a common use case.