Learning Node.js - CommonJS vs ES Modules

#Introduction

Node.js has a unique history when it comes to modules: it initially used CommonJS with require, then since version 12 fully supports ES Modules with import, the standard across the JavaScript ecosystem. Both still coexist, and you'll find both in production code.

Episode 4 compares the two module systems: syntax, internal mechanics, how to set the default mode via package.json, and the rules for mixing them. After this episode, you can read and write code in both formats without hesitation.

#CommonJS: require and module.exports

#Node.js's Original Module System

CommonJS is the module system that has carried Node.js since birth. Every file is treated as a separate module, and a file exposes its contents through the module.exports object:

math.js (CommonJS)

function tambah(a, b) {
  return a + b;
}
 
module.exports = { tambah };

Another file loads it with require:

app.js (CommonJS)

const { tambah } = require("./math.js");
 
console.log(tambah(2, 3));

The pattern module.exports = { tambah } exports an object, then require("./math.js") loads it and destructuring takes the tambah function. CommonJS hallmarks: execution happens synchronously when require is called, and the result is cached so a second call doesn't execute the file again.

#CommonJS-Specific Variables

In CommonJS, Node.js injects special variables: module, exports, require, __filename, and __dirname. The last two are very useful for composing file paths, as we used in episode 3.

#ES Modules: import and export

#The Modern JavaScript Standard

ES Modules (ESM) is the official module system of the JavaScript specification — used in browsers and Node.js. Its syntax is declarative and static, so analyzers can inspect dependencies without running code:

math.mjs (ESM)

export function tambah(a, b) {
  return a + b;
}

app.mjs (ESM)

import { tambah } from "./math.mjs";
 
console.log(tambah(2, 3));

Notice the difference: export directly marks the exposed function, and import { tambah } from "./math.mjs" loads it. In ESM, __dirname is not available — instead Node.js provides import.meta.url, which points to the current file's location.

#ESM Is Asynchronous

Unlike CommonJS, which is synchronous, ESM in Node.js executes asynchronously — very important for supporting top-level await, which is using await directly at the top level of a file without wrapping it in a function. This makes ESM code much cleaner for I/O operations.

#Determining the Module Mode

#The type Field in package.json

The file format is determined by the extension and the "type" field in package.json:

• Without "type" or with "type": "commonjs": .js files are treated as CommonJS.
• With "type": "module": .js files are treated as ES Modules.
• The .mjs extension is always ESM; the .cjs extension is always CommonJS.

{
  "name": "belajar-modul",
  "version": "1.0.0",
  "type": "module"
}

With "type": "module", all .js files in the project use the import syntax. New projects are recommended to use ESM — it's the direction of the industry standard and all subsequent examples in this series.

#Mixing Both Systems

#Flexible Interoperability

The good news: both systems can coexist. Node.js allows using import to load CommonJS modules, and using require to load ESM modules (specifically in .cjs files):

Load CJS from ESM

import math from "./math.cjs";
 
console.log(math.tambah(4, 5));

A CommonJS module exports the module.exports object, which automatically becomes the default export when loaded from ESM. That's why import math from "./math.cjs" directly gets the entire exports object without curly braces.

#Switching Between Formats Safely

When migrating a project from CommonJS to ESM, start with the files that have the fewest dependencies. Almost all modern third-party modules already provide ESM exports, while older packages can still be loaded from ESM via their default export. What to avoid: flipping "type" mid-project without planning, because it will trigger errors like ERR_REQUIRE_ESM or ERR_UNKNOWN_FILE_EXTENSION.

#Closing

Here's what to take away:

• CommonJS uses require and module.exports; synchronous and cached.
• ESM uses import and export; the modern JavaScript standard and asynchronous.
• The "type": "module" field makes .js files ESM.
• The .mjs and .cjs extensions force their respective formats.
• CJS modules can be loaded from ESM via the default export.
• New projects are recommended to use ES Modules.

In the next episode, episode 5, we'll discuss file I/O and basic streams — the modern fs/promises API, the concept of streams for large files, pipeline, and readline. You'll see why streaming isn't just a style choice, but a necessity for memory-efficient servers.