Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Pure ESM package

Pure ESM package

The package linked to from here is now pure ESM. It cannot be require()'d from CommonJS.

This means you have the following choices:

  1. Use ESM yourself. (preferred)
    Use import foo from 'foo' instead of const foo = require('foo') to import the package. You also need to put "type": "module" in your package.json and more. Follow the below guide.
  2. If the package is used in an async context, you could use await import(…) from CommonJS instead of require(…).
  3. Stay on the existing version of the package until you can move to ESM.

You also need to make sure you're on the latest minor version of Node.js. At minimum Node.js 12.20, 14.14, or 16.0.

I would strongly recommend moving to ESM. ESM can still import CommonJS packages, but CommonJS packages cannot import ESM packages synchronously.

ESM is natively supported by Node.js 12 and later.

My repos are not the place to ask ESM/TypeScript/Webpack/Jest/ts-node/CRA support questions.

FAQ

How can I move my CommonJS project to ESM?

  • Add "type": "module" to your package.json.
  • Replace "main": "index.js" with "exports": "./index.js" in your package.json.
  • Update the "engines" field in package.json to Node.js 14: "node": ">=14.16". (Excluding Node.js 12 as it's no longer supported)
  • Remove 'use strict'; from all JavaScript files.
  • Replace all require()/module.export with import/export.
  • Use only full relative file paths for imports: import x from '.';import x from './index.js';.
  • If you have a TypeScript type definition (for example, index.d.ts), update it to use ESM imports/exports.
  • Optional but recommended, use the node: protocol for imports.

Sidenote: If you're looking for guidance on how to add types to your JavaScript package, check out my guide.

Can I import ESM packages in my TypeScript project?

Yes, but you need to convert your project to output ESM. See below.

How can I make my TypeScript project output ESM?

  • Make sure you are using TypeScript 4.7 or later.
  • Add "type": "module" to your package.json.
  • Replace "main": "index.js" with "exports": "./index.js" in your package.json.
  • Update the "engines" field in package.json to Node.js 14: "node": ">=14.16". (Excluding Node.js 12 as it's no longer supported)
  • Add "module": "node16", "moduleResolution": "node16" to your tsconfig.json. (Example)
  • Use only full relative file paths for imports: import x from '.';import x from './index.js';.
  • Remove namespace usage and use export instead.
  • Optional but recommended, use the node: protocol for imports.
  • You must use a .js extension in relative imports even though you're importing .ts files.

Also make sure to read the official TypeScript guide.

If you use ts-node, follow this guide.

How can I import ESM in Electron?

Electron doesn't yet support ESM natively.

You have the following options:

  1. Stay on the previous version of the package in question.
  2. Bundle your dependencies with Webpack into a CommonJS bundle.
  3. Use the esm package.

I'm having problems with ESM and Webpack

The problem is either Webpack or your Webpack configuration. First, ensure you are on the latest version of Webpack. Please don't open an issue on my repo. Try asking on Stack Overflow or open an issue the Webpack repo.

I'm having problems with ESM and Next.js

You must enable the experimental support for ESM.

I'm having problems with ESM and Jest

Read this first. The problem is either Jest (#9771) or your Jest configuration. First, ensure you are on the latest version of Jest. Please don't open an issue on my repo. Try asking on Stack Overflow or open an issue the Jest repo.

I'm having problems with ESM and TypeScript

If you have decided to make your project ESM ("type": "module" in your package.json), make sure you have "module": "nodenext" in your tsconfig.json and that all your import statements to local files use the .js extension, not .ts or no extension.

I'm having problems with ESM and ts-node

Follow this guide and ensure you are on the latest version of ts-node.

I'm having problems with ESM and Create React App

Create React App doesn't yet fully support ESM. I would recommend opening an issue on their repo with the problem you have encountered. One known issue is #10933.

How can I use TypeScript with AVA for an ESM project?

Follow this guide.

How can I make sure I don't accidentally use CommonJS-specific conventions?

We got you covered with this ESLint rule. You should also use this rule.

What do I use instead of __dirname and __filename?

import {fileURLToPath} from 'node:url';
import path from 'node:path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(fileURLToPath(import.meta.url));

However, in most cases, this is better:

import {fileURLToPath} from 'node:url';

const foo = fileURLToPath(new URL('foo.js', import.meta.url));

And many Node.js APIs accept URL directly, so you can just do this:

const foo = new URL('foo.js', import.meta.url);

How can I import a module and bypass the cache for testing?

There's no good way to do this yet. Not until we get ESM loader hooks. For now, this snippet can be useful:

const importFresh = async modulePath => import(`${modulePath}?x=${new Date()}`);

const chalk = (await importFresh('chalk')).default;

Note: This will cause memory leaks, so only use it for testing, not in production. Also, it will only reload the imported module, not its dependencies.

How can I import JSON?

JavaScript Modules will eventually get native support for JSON, but for now, you can do this:

import fs from 'node:fs/promises';

const packageJson = JSON.parse(await fs.readFile('package.json'));

When should I use a default export or named exports?

My general rule is that if something exports a single main thing, it should be a default export.

Keep in mind that you can combine a default export with named exports when it makes sense:

import readJson, {JSONError} from 'read-json';

Here, we had exported the main thing readJson, but we also exported an error as a named export.

Asynchronous and synchronous API

If your package has both an asynchronous and synchronous main API, I would recommend using named exports:

import {readJson, readJsonSync} from 'read-json';

This makes it clear to the reader that the package exports multiple main APIs. We also follow the Node.js convention of suffixing the synchronous API with Sync.

Readable named exports

I have noticed a bad pattern of packages using overly generic names for named exports:

import {parse} from 'parse-json';

This forces the consumer to either accept the ambiguous name (which might cause naming conflicts) or rename it:

import {parse as parseJson} from 'parse-json';

Instead, make it easy for the user:

import {parseJson} from 'parse-json';

Examples

With ESM, I now prefer descriptive named exports more often than a namespace default export:

CommonJS (before):

const isStream = require('is-stream');

isStream.writable();

ESM (now):

import {isWritableStream} from 'is-stream';

isWritableStream();
@jaydenseric
Copy link

jaydenseric commented Aug 9, 2021

Most people don't realize that their imagination of a package that perfectly supports both ESM (for Node.js, Deno/browsers, and bundlers) and CJS consumers is impossible.

To avoid the dual package hazard, all the package's modules must be CJS with a single "default export" (module.exports =), with the exception of index files that are conditionally resolved for ESM consumers (via conditional exports) to allow proper named exports. This setup means everyone is running and bundling the same code, regardless if it's imported or required. It's incorrect for a package to publish the same API built twice; once to ESM files, and another time to CJS files. @StarpTech it appears all of the "popular projects that use it successfully" you listed are incorrect. If part of your codebase requires from them, and another imports the same thing, duplicated code will run/bundle.

Here's a correct example:

The downsides are:

  • Few people understand why it should be done this way, or how to do it correctly. The concepts are very abstract and package authors have a habit of publishing something that happens to work when they tested it locally for their particular projects, even if it's horribly broken for other kinds of projects. > 80% of published dual ESM/CJS packages cause the dual package hazard and most of the time the authors (doesn't really matter how famous they are) don't even know what that is.
  • The package author has to write and maintain primarily CJS code. This sucks, because:
    • You need to make sure all your dev tools support ESM and CJS modules, and can tell what the mode should be for any given file. Which they largely fail at even though tool authors have had years to get it right. Linters, etc. still suck at detecting the module type without elaborate manual config. The TypeScript team have purposefully sabotaged .mjs support! Tooling that needs to parse the source code (e.g. via Babel) to work has to have double the complexity in some cases because the AST for a CJS module (require calls, etc.) is very different to an ESM module (import statements, etc.).
    • You can't use any pure ESM dependencies, because your modules are CJS. This downside alone is a dealbreaker.
  • The package install size is slightly larger because index modules have to exist as both ESM and CJS files.
  • Your packages are only ESM on the surface.
    • You can't import any of the code in a browser or Deno, because the modules are all either CJS, or ESM that imports CJS and these runtimes can't deal with CJS at all.
    • CDN's that allow packages to be imported via URL for browsers or Deno have to do more fiddly work to convert all the CJS to serve pure ESM. This results in bugs and increases the barrier to entry for people that want to build or host their own.

IMO the JavaScript community has had the priorities wrong for a long time; we need to prioritize technical elegance, simplicity, DX, and documentation for package authors over package consumers. Otherwise we are building our castles on top of a foundation of mud only pigs enjoy working in.

I remember wishing 5 years ago that Node.js would just deprecate CJS and support ESM from the next major version. If only that had happened when the npm ecosystem was much smaller; literally hundreds, perhaps thousands of hours of my life have been wasted on CJS issues.

There is never going to be a time that it's painless to switch to pure ESM. The faster we rip the bandaid off and focus on publishing simple, standards-aligned packages for us all to build on, the better. All the people complaining have no idea that Deno is going to disrupt their entire world soon anyway, a runtime that only works with real ESM; browser-like HTTP/S imports.

@jaydenseric
Copy link

jaydenseric commented Aug 9, 2021

@dlong500

it might be nice if some of the major players who want to push ESM usage forward could help with the tooling in the ecosystem and not just the libraries

I used to think that we should wait for tools to be ready before republishing everything as pure ESM. But in reality, some of us have spent years attempting to raise issues and PRs fixing native ESM compat for big mainstream packages, to be met with a total lack of urgency or even outright hostility by project owners. We've been pushing Next.js for over 3 years to support native ESM (both in project code, and for dependencies) and there was zero prioritization until @sindresorhus lead the wave of publishing pure ESM anyway, forcing them to make some progress in canary releases in just the last few weeks. Here is a styled-jsx PR I raised 15 months ago to support Node.js ESM that still hasn't been merged.

Unfortunately the npm ecosystem doesn't prioritize the right kinds of things. Big budget brands build and market huge, monolithic frameworks with no separations of concerns that lock users in. Normies just install things based off of brand recognition, stars, and install counts so it's a vicious cycle that gets worse and worse.

If you're willing to look for lightweight, standards-aligned dev tools that have narrow focus (separation of concerns, so no lock-in) you will be pleasantly surprised that you can do almost anything you need with support for native ESM. For example, Jest (currently a 24.9 MB install size!) for years has been plagued with native ESM issues, along with all the other 10k+ star alternatives. So long ago I took months off work to publish a set of tiny standalone tools that have worked flawlessly to test all my own packages (that get millions of installs, so not toys):

After all these years they've only accumulated 21 stars combined. As they say; "you can lead a horse to water, but you can't make it drink". I even experienced cyber-bullying (since deleted and apologized for) for creating coverage-node, because it threatened the status quo for packages overlapping in purpose.

It's a bit like the Internet Explorer situation. If we support it because lazy orgs still use it, then said orgs won't update from it. Ad infinitum.

@jaydenseric
Copy link

jaydenseric commented Dec 12, 2021

Betting on CJS is like betting on Adobe Flash a few years ago. At the time people couldn't imagine Flash would be abandoned by every website and wouldn't even be installable in browsers. Flash devs made a lot of salty arguments, some similar to comments made here. In the end, proper web standards that are supported by browser runtimes win every time.

It is not deprecated in any sense

It most certainly is, in many common senses. Sure, the Node.js team have not declared the format deprecated by the runtime (yet). Deprecating the format isn't solely in the hands of the Node.js team though, individual package authors can also deprecate support for CJS consumers one a per-package basis when they republish as pure ESM. CJS "deprecation" is also decided by the entire JS community, which includes runtimes other than Node.js. CJS is garbage in the eyes of the Deno community, and even if they get Node.js CJS compatibility layers working it will still be considered a second-class format to standard ESM.

It's fine - and helpful! - to make dual packages.

With the huge caveat discussed here; the "dual" packages must avoid the dual package hazard. Barely any of the "dual" packages today successfully do so. Most people have a naive impression that dual packages ship all the code as both ESM and CJS, which is probably worse all things considered that just picking pure CJS or ESM.

the vast majority of the planet still uses CJS, and is likely to for the foreseeable future

Hard disagree.

Most developers are so dependant on build tooling they don't actually know how to write a CJS module; millions of developers have their source as ESM. To them, CJS is an implementation detail of Babel, Next.js and Node.js. Most of the installs on npm flow from a few popular libraries/frameworks that suck in an ungodly amount of dependencies on install. If one or two switch to pure ESM and update their dependencies to newer pure ESM versions, overnight millions of CJS installations evaporate.

There is a network effect where once packages start flipping to pure ESM, CJS packages that consume it also have to flip. The only reason this hasn't spread like wildfire already is because a few dev tools (namely TypeScript, Next.js, and Jest) have refused or delayed Node.js ESM support, and once they support ESM properly we'll be unblocked from a mad scramble to ESM over the next year or so. In 2 years, we might have an ecosystem of maintained packages that are almost entirely pure ESM.

It's frustrating to see people defend lazy billion dollar corporations (Microsoft, Vercel ($2.5 billion in funding), Facebook) who throw their weight around by either spreading FUD or inaction, instead of supporting the passionate open source package authors that want to publish, promulgate, and use the best technology possible. Once these corporations have been forced to take standard ESM seriously, the fixes don't take that long in the scheme of things to work out. They could have gone to the same effort years earlier and saved the ecosystem so much grief. It's like getting mega corporations off fossil fuels; imagine if everyone waited for the worlds richest corporations to change their policy first before everyone else follows and invests in and uses renewables. Progress would never happen. People need to stop putting big brand names on a pedestal; their policies are not always the best either for the world or for you. Sometimes you have to publicly challenge the narrative, lead by example, and inspire positive change. In this regard, @sindresorhus has the respect of many of us.

TypeScript have mostly figured out ESM/.mjs/.cjs compat but got cold feet and dropped most of it for the TS v4.5 release; they plan to publish the fixes in v4.6 which is scheduled for February 22, 2022. It's outrageous that Microsoft isn't treating blatant Node.js incompatibilities as emergencies to be patched sooner, but being Christmas the next 2 months will zoom by.

Next.js and their inability to process pure ESM dependencies was the reason I didn't migrate a few of my own Next.js / front end related packages to pure ESM. They still haven't fixed bugs relating to ESM project modules (e.g. vercel/next.js#17806), but they have fixed support for pure ESM dependencies which was the main problem. Accordingly, I've gone ahead the past few weeks and converted several more packages to pure ESM. In time, others will do the same too.

I've got zero sympathy for people that were relying on Jest's ability to transpile source on the fly and screw around with concerns of the runtime by hacking the imports, instead of testing the actual distribution code properly via tests that are regular JS modules that don't need a special engine other than Node.js to run. Regardless, one way or another Jest will resolve all the Node.js ESM compat issues as it's an existential issue for the viability for the tool, or people can rewrite their tests.

The ESM flippening has already begun, but in a few months there will be no brakes on the train.

@jimmywarting
Copy link

jimmywarting commented Dec 12, 2021

I agree with you @jaydenseric... some typescript user think they use esm while in fact they are transpiling to cjs without even knowing it.

I would not call cjs depricated... legacy is a more correct word for it... it will likely never go away for a foreseeable future but new code should start to using esm by default now...

From my own experiences we at node-fetch fist wanted to use import and if we wanted to have dual support then it meant that we would have to convert everything back to cjs (even sup dependencies), which we didn't want to do anymore. We didn't want to duplicate all our code. and we didn't want to reintroduce a compiler. And We now also depend on other esm only packages. if we wanted to have dual support at this stage now then it meant that we would have to embed our sub dependencies into node-fetch and transpile them to cjs as well to keep a own copy for our self, which would duplicate all the code and classes and interfere with instances.
If someone where to depend on the same version of any of the public classes or sup packages (formdata, header, blob, file, abortsignal whatwg streams) or whatever then it would just be conflicting with instanceof checks and node-fetch would be stuck on one internal version of one package while you might depend on some newer version.

dual support is just a hazard that i want to avoid. cjs don't work in any other env other than NodeJS and NodeJS supports ESM now so why would one want to use cjs still? NodeJS is not the only platform, developers want their code to work cross other env too, even if you built something in cjs that was solo built to run in NodeJS, then there will always be that one guy who are going to wish that you built it as ESM so they can import it without the need of npm or any bundler for Deno or the Browaser.

Someone must start converting to pure ESM at some point. We can't sitt around and wait for all 23k packages who depend on node-fetch to switch to esm first. Or the other way around. We can't sitt around and wait for sub dependencies or build tools to all be ESM first. And we can't control how gulp, webpack, jest, rollup, typescript, babel, etc all deal with cjs and esm. then we would be stuck with cjs/dual packages forever.

It's just a chicken and the egg paradox of who should convert to ESM first... typescript and other have long stick there head in the sand about extension less paths and depend on cjs to resolve the path. This can't continue like this when we have remote path resolver that are dynamic lazy imported

i fear that ppl will start using the experimental-specifier-resolution flag and hope that it stays implicit for remote http path resolvers sakes
i wish experimental-specifier-resolution was never introduced into NodeJS, it's considered a bad practices now to depend on index and extensionless paths.

I don't have much sympathy for typescript user either. typescript isn't javascript... i work with javascript, nothing else.

sindre have my respect and esm is the feature, weather you like it or not. it's time to switch

@jaydenseric
Copy link

jaydenseric commented Dec 13, 2021

@ljharb

The dual package "hazard" exists if and only if your package is stateful, or relies on identity. The vast majority of packages don't, and thus, for the vast majority of packages, there is no such thing as a dual package hazard.

This is simply untrue. Runtime identity issues are just one symptom of the dual package hazard. If you are bundling, consuming the ESM and CJS formats of the same code in different parts of your code base / dependency graph result in the same code being bundled twice, which slows your builds, and increases the download and parse times for users loading the web app. If you are not bundling, loading and parsing more code still has a performance cost.

Technically not the dual package hazard, but another downside regardless, is if every package in node_modules duplicated it's API in seperate ESM and CJS files, node_modules takes up considerably more disk space. node_modules install size is a serious problem the industry is facing; it slows installations in CI or for deployments, and increases disk space usage increasing costs or exceeding environment limits (particularly for serverless).

@OmgImAlexis

you can check the existence of all of those files at the same time and then choose which to use. It's not going to take any noticeable difference in time.

There are good reasons automatic file extension resolution was dropped from the final Node.js ESM system, and it isn't a thing in Deno or browsers either. It's a bad idea. Looking up all the possible resolutions is prohibitive if the modules are imported using HTTP imports over network; either in a server environment (Deno) or in browsers for apps using ESM for real on the client. It also significantly complicates and slows a lot of dev tooling that statically analyses imports. For an example of just one tool, look at all the extra complexity supporting it added to find-unused-exports:

@sindresorhus
Copy link
Author

sindresorhus commented Feb 4, 2022

This discussion thread is not productive and I never meant for this gist to be a place for everyone to went about ESM.

CONSIDER THIS THREAD LOCKED

ANY COMMENTS AFTER THIS ONE WILL BE DELETED

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment