Releasing JavaScript

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 package.json:

"type": "module"

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 exports.

Using the exports field

Publishing responsibly. Switching to using the exports field, 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.json as one of the exports, as some build tools depend on being able to read it.

Assorted reading materials

Get Ready For ESM. JavaScript Modules will soon be a… | by Sindre Sorhus | 🦄 Sindre Sorhus’ blog

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.