Module Systems (CJS & ESM)

The Tale of Two Systems

In the beginning, JavaScript had no official way to share code between files. It was the Wild West. When Node.js was built, it needed a way to manage dependencies, so it adopted CommonJS (CJS). This became the standard for years.

Then came ES Modules (ESM)—the official, standardized module system for JavaScript, aimed at unifying the browser and the server. Now, Node.js speaks both languages, but they work quite differently.

Think of it like two different logistics companies operating on the same construction site.

CommonJS (The Legacy Standard)

CommonJS is the “Industrial Supply Chain.” It’s practical, synchronous, and built for the server.

When you use require(), you are filling out a Requisition Form and handing it to a clerk who immediately runs to the warehouse, grabs the item, and puts it in your hand before you can do anything else.

• require(): The order form. It loads the file synchronously.
• module.exports: The shipping container. Whatever you put in here is what gets shipped.

The Requisition (require)

Blocking Operation

require is synchronous. The script halts until the required file is found, read, and executed. This is fine on a server (files are local), but terrible in a browser (files are over a network).

./app.js

// "Go get the http module right now."
const http = require('http');

// "Go get our tools."
const tools = require('./utils');

The Shipment (module.exports)

./utils.js

const tools = {
  hammer: '🔨',
  drill: '🔫',
};

// Pack the container
module.exports = tools;

---

ES Modules (The Modern Standard)

ESM is the “Architectural Blueprint.” It’s static, asynchronous-friendly, and standardized across the entire JS ecosystem (browsers included).

When you use import, you are drawing a dependency line on a blueprint. The engine scans all these lines before running the code to build a complete dependency graph.

• import: The dependency declaration.
• export: The public interface.

The Blueprint (import)

To use ESM in Node, you either need to use the .mjs extension or add "type": "module" to your package.json.

./app.js

// "I will need these items to function."
import http from 'node:http';
import { hammer } from './utils.js'; // Note the extension!

The Offerings (export)

./utils.js

export const hammer = '🔨';
export const drill = '🔫';

// Or a default export
export default { hammer, drill };

---

The Showdown: CJS vs. ESM

Which one should you use? Here is the breakdown.

Feature	CommonJS (CJS)	ES Modules (ESM)
Syntax	require / module.exports	import / export
Loading	Synchronous (Dynamic)	Asynchronous (Static Analysis)
Top-Level Await	No (requires async wrapper)	Yes (very distinctive)
Browser Native?	No	Yes
__dirname	Available	Not available (needs polyfill)
Magic	require can be dynamic	import paths are static

Pro-Tip

Starting a New Project? Go ESM. It’s the future. - working on an Existing Backend? CJS is likely what you’ll see. It’s not going anywhere soon.

Warning:

You can import CJS into ESM, but you cannot require() an ESM file in CJS.

✅ import module from './commonjs-file.js' - Works!

❌ require('./esm-file.mjs') - Crashes! Use await import() instead

---

Extra Bits & Bytes

CommonJS vs ES Modules Demo Repo

---

⏭ File System Freedom with FS

In Node.js, we’re free from the sandbox of the browser. We can do (almost) anything we want with folders and files on the server.