CommonJS vs. ES Modules in Node.js

1. CommonJS (CJS): The Original Node.js Module System

When Node.js was created, JavaScript had no built-in module system. To enable server-side development with its need for code organization, Node.js adopted and popularized its own system: CommonJS.

The syntax is likely familiar to you: you use require() to import a module and module.exports (or exports) to expose functionality.

To see a quick recap of the syntax, watch the first part of the following video.

The syntax is straightforward, but the real distinction lies in the loading behavior. To explore this, let's dive into a more detailed explanation of CJS mechanics.

A key takeaway from the reading is that when you require a module, you are getting a copy of the value of module.exports at that point in time. It's an object, and that object is passed by reference, but the properties themselves are copies. This has important implications, especially when compared to ES Modules.

2. ES Modules (ESM): The Modern Standard

With the ES2015 (ES6) specification, JavaScript finally received its own official, standardized module system. ES Modules (ESM) were designed from the ground up to be the universal standard, working across different environments like browsers and Node.js.

The syntax uses the import and export keywords.

The most significant difference from CommonJS is that ESM loading is asynchronous and static.

This "live binding" feature is a powerful distinction. It also comes with a security benefit. Since the imported bindings are read-only, one module cannot accidentally (or maliciously) mutate the exports of another.

3. Comparison and Interoperability in Node.js

The JavaScript ecosystem has been in a long transition period from CJS to ESM. Node.js now supports both, but you need to explicitly tell the runtime which system you're using.

This short, high-level video succinctly explains the core reason for the split and the resulting interoperability challenges.

So, how do we manage this divide in a Node.js project?

How to use ESM in Node.js:

You have two primary methods:

1. Add "type": "module" to your package.json file. This tells Node.js to treat all .js files in your project as ES Modules.
2. Use the .mjs file extension for your module files. Node.js will always interpret .mjs files as ES Modules.

How to use CJS in an ESM-first project:

• If your package.json has "type": "module", you can still write CommonJS code by naming the files with the .cjs extension.

How to import ESM from a CJS module:

• You cannot use require() to import an ES Module. Instead, you must use the dynamic import() function, which returns a Promise that resolves with the module's contents.

// In a CommonJS file (e.g., index.js)
async function loadMyModule() {
  const myModule = await import('./my-module.mjs');
  myModule.doSomething();
}

loadMyModule();

The video we watched earlier also covers these practical aspects of configuration.

Summary of Differences

Conclusion

You now have a deep understanding of the two module systems that govern the Node.js landscape. This knowledge goes beyond simple syntax and touches on the fundamental design philosophies of each system.

Key Takeaways:

• CommonJS (CJS) is Node.js's legacy module system. It is synchronous, dynamic, and loads modules at runtime using require(). It exports a copy of the module.exports object.
• ES Modules (ESM) are the official JavaScript standard. They are asynchronous, static, and are parsed before any code execution. import creates a live, read-only binding to the original exported value, not a copy.
• Loading Behavior is the Core Difference: CJS's synchronous nature was suited for fast local file access on a server. ESM's asynchronous, phased approach was designed to be universal, accommodating network latency in browsers while also enabling optimizations.
• Interoperability: Node.js supports both systems, but you must be explicit. Use "type": "module" in package.json or .mjs/.cjs file extensions to control how files are interpreted. To load ESM from CJS, you must use the dynamic import() function.

What's Next?

With a solid grasp of the Node.js runtime and its module systems, you are now ready to build a web server. In the next lesson, we will introduce Express.js, the most popular web framework for Node.js. We will explore its core architectural concept: the middleware pattern, and see how require and import are used to structure a real Express application.