From CommonJS to ES Modules

JavaScript has evolved from a simple scripting language for browsers into a powerful tool for building complex applications. One of the key aspects of this evolution is the introduction of modules, which allow developers to organize code more effectively. In this article, we will explore two major module systems in JavaScript: CommonJS and ES Modules (ESM). We'll discuss how they work, their differences, and when to use each.

---

Why Do We Need Modules?

Before modules were introduced, JavaScript developers had to rely on global variables, which led to naming conflicts and poor maintainability. Modules help solve this problem by:

• Encapsulating functionality

• Reusing code across files

• Managing dependencies cleanly

---

A Brief History of JavaScript Module Systems

1. Global pattern: Early JavaScript files simply declared variables and functions in the global scope.

2. IIFE (Immediately Invoked Function Expressions): Provided encapsulation.

3. AMD (Asynchronous Module Definition): Used in browsers (e.g., RequireJS).

4. CommonJS (CJS): Standard for Node.js applications.

5. ES Modules (ESM): Official ECMAScript module system, supported natively in browsers and modern Node.js.

---

CommonJS (CJS)

CommonJS was designed to make server-side JavaScript (Node.js) modular.

Syntax Example:

// math.js
function add(a, b) { return a + b; }
module.exports = { add };

// app.js
const math = require('./math');
console.log(math.add(2, 3));

Key Features:

• Uses require() and module.exports

• Synchronous loading

• Modules are cached after the first import

• Works well in Node.js but not in browsers without bundlers

---

ES Modules (ESM)

ES Modules were introduced in ES6 (2015) and are now the standard way to structure JavaScript applications.

Syntax Example:

// math.js
export function add(a, b) { return a + b; }

// app.js
import { add } from './math.js';
console.log(add(5, 7));

Key Features:

• Uses import/export syntax

• Asynchronous and statically analyzable (tree shaking)

• Supported in browsers and Node.js

• Strict mode by default

• Can use top-level await

---

Named vs Default Exports

Named Exports:

export const PI = 3.14;
export function area(r) { return PI * r * r; }

Default Export:

export default function greet() {
  return "Hello";
}

Avoid mixing both in one file to maintain clarity.

---

CommonJS vs ES Modules: A Comparison

---

Performance and Optimization

• CJS blocks code execution while loading modules.

• ESM supports async loading and tree shaking for smaller bundles.

• Build tools like Webpack, Rollup, and Vite prefer ESM.

---

Interoperability Issues

Node.js supports both CJS and ESM, but mixing them can cause issues.

Import CJS in ESM:

import pkg from 'some-cjs-package';
const actual = pkg.default;

Import ESM in CJS:

(async () => {
  const { default: mod } = await import('./esm-module.mjs');
})();

---

Migrating from CommonJS to ESM

1. Rename files to .mjs or set "type": "module" in package.json

2. Replace require() with import

3. Replace module.exports with export

4. Adjust third-party module imports if necessary

---

Common Mistakes

• Forgetting file extensions in ESM

• Mixing module types incorrectly

• Using top-level await without support

• Destructuring CommonJS default exports

---

Real World Usage

• Frontend frameworks (React, Vue): Fully ESM-based

• Node.js tools: Often use CJS, slowly moving to ESM

• Libraries:

  • Lodash: Offers both

  • Axios: ESM-first

• Bundlers: Prefer ESM for better optimization

---

Best Practices

• Use ESM for modern projects

• Prefer named exports

• Keep modules small and focused

• Avoid unnecessary mixing of CJS and ESM

---

Conclusion

Modules are the foundation of modern JavaScript development. While CommonJS remains relevant in many environments, ES Modules offer better performance, cleaner syntax, and are the future of JavaScript. Understanding both ensures you're equipped to work on legacy and modern codebases alike.

---

Further Reading

• MDN Modules Guide

• Node.js Module Documentation

• JavaScript.info on Modules

• Rollup Documentation