Skip to main content

ECMAScript (ESM) vs CommonJS (CJS)

Basics​

This document provides a very basic overview, please refer to the linked references for more information.

What is a module?​

A module is simply a JavaScript or TypeScript file.

What is module system?​

A module is a collection of JavaScript code written in a file. A module's variables, functions are not available for use unless they are exported from the module file.

There are two main module systems:

How to determine my module system?​

Look at the type field in package.json.

The "type" field defines the module format that Node.js uses for all .js files that have that package.json file as their nearest parent - Node.js

info

CommonJS is used if type field is not defined.

ESM​

package.json
{
    "type":"module"
}

CJS​

package.json
{
    "type":"commonjs"
}

Import in CJS vs ESM​

ESM: Imports should end with a extension.

vs

CJS: I don't care!

info

In the case of TypeScript or JavaScript, please use the extension .js

import { helper } from "./foo"; // ❌ only works in CJS

import { helper } from "./foo.js"; // ✅ works in ESM & CJS