Making the switch to native ESM packages
Status: work in progress.
Using ES modules natively in Node
Node.js versions 12 and later support ES modules natively. To switch your whole package to ES modules, include
type: module in your
This instructs Node.js to consider all the
.js files in your project folder to be ES modules.
Publishing ES modules to npm
There are several approaches here. You could point your
main file to the ESM entry point, or use the newer
Publishing responsibly. Switching to using the
exportsfield, or changing the exports (with the exception of adding new exports), is a breaking change and entails a major version bump in semver.
When using the
exports field, you restrict what can be imported from the project.
It's good practice to include
package.jsonas one of the exports, as some build tools depend on being able to read it.
Assorted reading materials
Modules: Packages | Node.js v16.9.1 Documentation
Pure ESM package
Titus 🇵🇸 on Twitter: "The npm registry (±January 2010) contains ±1.7m unique packages. 1.5m are “CJS”†, 4k are dual ESM/CJS (through an export map), 190k are faux-ESM (non standard `module` field supported by certain bundlers), and 14.5k are ESM-only" / Twitter
proposal-pkg-exports, Proposal for Bare Module Specifier Resolution in node.js
Node Modules at War: Why CommonJS and ES Modules Can’t Get Along by Dan Fabulich
CJS vs ESM. No, this is not yet another rant… by Andrea Giammarchi.