CommonJS vs ESM differences in Node.js - Trade-offs & Expert Analysis

Overview - CommonJS vs ESM differences

What is it?

CommonJS and ESM are two ways to organize and share code in Node.js. CommonJS uses require() to load modules, while ESM uses import/export syntax. They help split code into reusable pieces so programs stay clean and manageable. Understanding their differences helps you write better Node.js applications.

Why it matters

Without module systems like CommonJS or ESM, all code would be in one big file, making it hard to find, fix, or reuse parts. These systems let developers share code easily and keep projects organized. Knowing their differences prevents bugs and helps you use modern JavaScript features effectively.

Where it fits

Before learning this, you should know basic JavaScript syntax and how to write simple programs. After this, you can explore advanced Node.js features, bundlers, and how modules work in browsers.

Mental Model

Core Idea

CommonJS and ESM are two different languages for talking between code files, each with its own rules and timing for sharing pieces of code.

Think of it like...

It's like two different ways to send packages: CommonJS is like sending a package immediately with everything inside, while ESM is like sending a list of items that can be picked up or changed anytime before delivery.

┌───────────────┐       ┌───────────────┐
│   CommonJS    │       │      ESM      │
├───────────────┤       ├───────────────┤
│ Uses require()│       │ Uses import   │
│ Loads modules │       │ and export    │
│ synchronously │       │ asynchronously│
│ Exports object│       │ Exports live  │
│ copies        │       │ bindings      │
└──────┬────────┘       └──────┬────────┘
       │                       │
       │                       │
       ▼                       ▼
  Modules loaded          Modules loaded
  at runtime             before runtime

Build-Up - 7 Steps

1

Foundation

What is CommonJS module system

Concept: Introduces CommonJS as the original Node.js module system using require and module.exports.

CommonJS lets you split your code into files called modules. You use require('module') to bring code from another file. To share code, you assign it to module.exports. This system loads modules when your program runs, one by one.

Result

You can organize code into separate files and use require() to access their exports synchronously.

Understanding CommonJS shows how Node.js originally handled code sharing and why require() feels like a normal function call.

2

Foundation

What is ESM module system

Concept: Introduces ECMAScript Modules (ESM) using import/export syntax standardized in JavaScript.

ESM is the modern way to share code using import and export keywords. You write export to share parts of your code, and import to bring them in. ESM loads modules before running your program, allowing better optimization and static analysis.

Result

You can write cleaner, declarative code with import/export and benefit from faster loading and better tooling.

Knowing ESM helps you use the latest JavaScript features and understand how modules work in browsers and modern Node.js.

3

Intermediate

Synchronous vs asynchronous loading

🤔Before reading on: Do you think CommonJS loads modules synchronously or asynchronously? What about ESM?

Concept: Explains the timing difference: CommonJS loads modules during runtime synchronously, ESM loads asynchronously before runtime.

CommonJS uses require(), which pauses code to load the module immediately. ESM uses import, which is asynchronous and loads modules before the program runs. This means ESM can optimize loading and detect errors early.

Result

CommonJS modules block execution until loaded; ESM modules allow non-blocking loading and better performance.

Understanding loading timing clarifies why ESM supports top-level await and static analysis, unlike CommonJS.

4

Intermediate

Exports: copies vs live bindings

🤔Before reading on: Do you think CommonJS exports are live updates or fixed copies? What about ESM exports?

Concept: Shows that CommonJS exports a copy of the value at export time, while ESM exports live references that update if changed.

In CommonJS, module.exports is a snapshot of the exported value. If the original changes later, the import does not see it. In ESM, exported variables are live bindings, so imports see updates automatically.

Result

ESM imports reflect changes in exported values; CommonJS imports do not update after initial load.

Knowing this difference helps avoid bugs when modules change state after export.

5

Intermediate

Interop challenges between CommonJS and ESM

🤔Before reading on: Can you use require() to load an ESM module directly? Can you import a CommonJS module with import syntax?

Concept: Explains the difficulties mixing CommonJS and ESM modules and how Node.js handles interoperability.

CommonJS cannot directly load ESM modules using require(). ESM can import CommonJS modules but treats their exports as a default object. Node.js provides ways like dynamic import() and special flags to help mix both systems.

Result

Mixing module types requires care and specific syntax to avoid runtime errors.

Understanding interop prevents common errors when migrating or combining module types.

6

Advanced

Package configuration and file extensions

🤔Before reading on: How does Node.js know if a file is CommonJS or ESM? Is it based on file extension or config?

Concept: Details how Node.js uses package.json and file extensions (.js, .mjs, .cjs) to determine module type.

Node.js treats .cjs files as CommonJS and .mjs files as ESM by default. For .js files, the package.json 'type' field controls the module system: 'type':'module' means ESM, otherwise CommonJS. This affects how your code is parsed and loaded.

Result

You can control module type per file or package, enabling gradual migration or mixed projects.

Knowing this helps avoid confusing errors and plan project structure effectively.

7

Expert

Performance and tooling implications

🤔Before reading on: Do you think ESM or CommonJS offers better performance and tooling support in modern Node.js?

Concept: Explores how ESM enables better static analysis, tree shaking, and faster startup compared to CommonJS.

Because ESM imports are static and known before runtime, tools can optimize code by removing unused parts (tree shaking). ESM also supports top-level await and better caching. CommonJS's dynamic require limits these optimizations. Modern Node.js versions optimize ESM loading for performance.

Result

Using ESM can lead to smaller bundles, faster startup, and improved developer experience.

Understanding these benefits guides choosing ESM for new projects and modernizing legacy code.

Under the Hood

CommonJS modules are wrapped in a function that provides exports, require, and module objects. When require() is called, Node.js synchronously reads, compiles, and executes the module code, caching the exports object. ESM modules are parsed statically before execution, building a dependency graph. Imports are linked as live references, and modules execute asynchronously in order, allowing features like top-level await.

Why designed this way?

CommonJS was designed for simplicity and synchronous loading in server environments where blocking is acceptable. ESM was designed by the JavaScript standards committee to support static analysis, asynchronous loading, and compatibility with browsers. Node.js adopted ESM later to align with the web and modern JavaScript standards, balancing backward compatibility with innovation.

CommonJS Loading Flow:
┌───────────────┐
│ require('mod')│
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Read & execute│
│ module code   │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Cache exports │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Return exports│
└───────────────┘

ESM Loading Flow:
┌───────────────┐
│ Parse imports │
│ statically    │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Build graph   │
│ of modules    │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Link live     │
│ bindings      │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Execute async │
│ modules       │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Can you use require() to load an ESM module without any special setup? Commit yes or no.

Common Belief: You can always use require() to load any module, including ESM modules.

Reality: require() cannot load ESM modules directly; you must use import() or configure Node.js to handle ESM.

Why it matters: Trying to require an ESM module causes runtime errors, blocking development and causing confusion.

Quick: Do CommonJS exports update automatically if the exported variable changes? Commit yes or no.

Common Belief: CommonJS exports are live and reflect changes after export.

Reality: CommonJS exports are copies at export time and do not update if the original changes.

Why it matters: Assuming live updates can cause bugs where imported values are stale or inconsistent.

Quick: Is the file extension alone enough to determine if a file is ESM or CommonJS? Commit yes or no.

Common Belief: File extension (.js) always determines module type regardless of package.json.

Reality: The package.json 'type' field can override .js files to be treated as ESM or CommonJS.

Why it matters: Ignoring package.json settings leads to confusing errors and unexpected module behavior.

Quick: Does ESM loading happen synchronously like CommonJS? Commit yes or no.

Common Belief: ESM modules load synchronously just like CommonJS modules.

Reality: ESM modules load asynchronously before runtime, enabling better optimization and features like top-level await.

Why it matters: Misunderstanding loading timing can cause incorrect assumptions about code execution order and bugs.

Expert Zone

1

ESM's static structure allows bundlers to perform tree shaking, removing unused code automatically, which CommonJS cannot do effectively.

2

Top-level await in ESM lets you write asynchronous initialization code without wrapping in async functions, improving readability and startup flow.

3

Node.js caches modules differently for CommonJS and ESM, affecting how changes in code during runtime or testing behave.

When NOT to use

Avoid mixing CommonJS and ESM in the same project unless necessary; prefer full ESM for new projects. For legacy codebases heavily using CommonJS, consider gradual migration or tools like Babel. Use CommonJS if you need synchronous loading or compatibility with older Node.js versions.

Production Patterns

In production, many projects use ESM for new code to leverage modern JavaScript features and better tooling. Legacy modules remain in CommonJS. Tools like dynamic import() and conditional exports in package.json help bridge both. Bundlers often convert ESM to optimized bundles for browsers.

Connections

JavaScript Promises

ESM's asynchronous loading relates to how Promises handle async operations.

Understanding Promises helps grasp why ESM modules load asynchronously and support top-level await.

HTTP/2 Multiplexing

Both ESM and HTTP/2 optimize loading by allowing multiple resources to load in parallel without blocking.

Knowing HTTP/2's parallelism clarifies why asynchronous module loading improves performance.

Supply Chain Management

Module systems manage dependencies like supply chains manage parts delivery.

Seeing modules as parts delivered on time helps understand why static analysis and live bindings matter.

Common Pitfalls

#1 Trying to require() an ESM module directly.

Wrong approach:

const mod = require('./module.mjs');

Correct approach:

import mod from './module.mjs';

Root cause:

Misunderstanding that require() only works with CommonJS modules.

#2 Assuming exported variables in CommonJS update after export.

Wrong approach:

module.exports.value = 1;
// later
module.exports.value = 2;
// importers see updated value automatically

Correct approach:

Use functions or objects to share mutable state explicitly.

Root cause:

Not knowing CommonJS exports are copies, not live references.

#3 Ignoring package.json 'type' field and mixing .js files with different module types.

Wrong approach:

// package.json has "type": "module"
// but code uses require() in .js files
const mod = require('./mod.js');

Correct approach:

// package.json has "type": "module"
import mod from './mod.js';

Root cause:

Not understanding how Node.js determines module type from config and extension.

Key Takeaways

CommonJS and ESM are two module systems in Node.js with different syntax and loading behavior.

CommonJS loads modules synchronously at runtime and exports copies, while ESM loads asynchronously before runtime and exports live bindings.

ESM supports modern JavaScript features like static analysis, tree shaking, and top-level await, improving performance and developer experience.

Mixing CommonJS and ESM requires care due to interoperability challenges and configuration details like file extensions and package.json settings.

Choosing the right module system depends on project needs, compatibility, and future-proofing your codebase.