CommonJS (require/module.exports)

SECTION 1

Historical Context & Motivation

When JavaScript was first created in 1995, it was designed to run inside web browsers—short scripts that made buttons clickable or validated a form. Every script shared one big, global space, which meant that if two scripts used the same variable name, they could overwrite each other. As programs grew larger, this became a real headache. Developers needed a way to split code into modules—self-contained files that could share only what they chose to share.

In 2009, a project called Node.js brought JavaScript to the server side—meaning you could run JavaScript outside of a browser, on your own computer or a web server. Node.js needed a module system right away, because server programs are often large and complex. The solution was CommonJS, a standard that introduced two key tools: require() to load a module, and module.exports to make parts of a module available to other files.

1995

JavaScript Is Born

Brendan Eich creates JavaScript in just 10 days for the Netscape browser. All scripts share a single global scope with no module system.

2009

Node.js & CommonJS

Ryan Dahl releases Node.js, which adopts the CommonJS specification. Developers can now write server-side JavaScript with require() and module.exports.

2010

npm Launches

The Node Package Manager (npm) is released, creating a massive ecosystem of CommonJS modules that developers can install and require in their projects.

2015

ES Modules Arrive

ECMAScript 2015 (ES6) introduces a new, built-in module syntax using import and export. CommonJS remains the default in Node.js for years afterward.

2020+

CommonJS Still Everywhere

Although ES Modules gain support in Node.js, millions of existing packages and projects still rely on CommonJS. Understanding it is essential for any Node.js developer.

The central question CommonJS answers is: How do you break a large JavaScript program into smaller, reusable files that can safely share code without polluting a single global namespace?

SECTION 2

Core Principles & Definitions

CommonJS revolves around a small set of ideas that keep your code organized and predictable. Every file in a Node.js project is treated as its own module. The variables and functions inside a file are private by default—nothing leaks out unless you explicitly choose to export it. Let's break down the foundational concepts.

Module = File

In CommonJS, each .js file is automatically a separate module with its own private scope. Variables declared inside one file cannot be accessed by another file unless explicitly exported.

module.exports

Every module has a special object called module.exports. Whatever you assign to this object becomes the module's public interface—the stuff other files can use.

require()

The require() function loads another module by file path. It returns whatever that module placed on module.exports, giving you access to its public code.

Synchronous Loading

CommonJS loads modules synchronously—one at a time, in order. When Node.js hits a require() call, it pauses, reads the file, runs it, and then continues with the next line.

Caching

Once a module is loaded, Node.js caches it. If you require() the same file from multiple places, the code inside only runs once. Every caller gets the same cached exports object.

✦ KEY TAKEAWAY

Think of each module like a locked toolbox. By default, nobody can reach inside. module.exports is like labeling certain tools and placing them on a shelf where others can grab them. require() is like walking over to that shelf and picking up what you need. You only get the tools the owner chose to share—everything else stays locked away.

SECTION 3

Visual Explanation — How require and module.exports Connect Files

The diagram shows two files. On the left, math.js keeps PI and square private (gray text) while exporting areaOfCircle (green text). On the right, app.js uses require('./math') (yellow arrow) and receives only the exported object (green arrow). Trying to access PI or square from app.js returns undefined.

Notice the key idea in the diagram: the public/private boundary is controlled entirely by what you place on module.exports. The variable PI and the helper function square are used internally to compute the area, but they never leave math.js. This keeps your code clean, prevents accidental conflicts, and makes it clear exactly what each module is responsible for.

SECTION 4

How CommonJS Works Under the Hood

When you call require('./math'), Node.js performs several steps behind the scenes. Understanding this process helps you predict how your modules behave and debug problems when something goes wrong.

The Five-Step require() Process

Resolve — Node.js figures out the absolute file path. If you write require('./math'), it looks for math.js in the same directory. If you write require('lodash') (no dot), it looks in the node_modules folder.
Check Cache — Node.js checks if this module was already loaded. If so, it returns the cached module.exports immediately without re-running the file.
Wrap — Node.js wraps the file's code in a special function that provides require, module, exports, __dirname, and __filename as local variables. This wrapper is what creates each module's private scope.
Execute — The wrapped code runs from top to bottom. Any assignments to module.exports happen during this step.
Return — Node.js returns the value of module.exports to the calling file.

The Module Wrapper Function

Step 3 is the secret sauce. Before your code ever runs, Node.js wraps it like this:

MODULE WRAPPER

(function(exports, require, module, __filename, __dirname) { // your module code goes here });

exports is a shortcut reference to module.exports. require is the function to load other modules. __filename and __dirname hold the current file's full path and directory. Because your code is inside a function, your variables are local—not global.

⚠️ exports vs. module.exports

The variable exports is just a convenience reference that points to module.exports. You can add properties to it like exports.myFunc = ..., but if you reassign exports itself (e.g., exports = { ... }), you break the link and nothing gets exported. When in doubt, always use module.exports.

SECTION 5

Common Export Patterns

There are several ways to structure your exports in CommonJS. Each pattern suits a different situation. Let's look at the three most common approaches you'll encounter in real Node.js projects.

Three side-by-side export patterns. Pattern 1 (cyan) exports an object with multiple functions. Pattern 2 (violet) exports a single function directly. Pattern 3 (pink) exports a class. The bottom panel explains when each pattern is most useful.

The most important thing to remember is that module.exports can hold any JavaScript value—an object, a function, a class, a string, or even a number. Whatever you assign to it is exactly what the consumer receives when they call require(). In practice, most modules export either an object (Pattern 1) or a single function (Pattern 2).

SECTION 6

Worked Example — Building a Temperature Converter Module

Let's walk through creating a module from scratch and using it in another file. We'll build a small temperature converter that converts between Fahrenheit and Celsius.

Temperature Converter with CommonJS

Step 1 — Create the module file (tempConverter.js)Create a new file called tempConverter.js. Inside, define two functions: one to convert Fahrenheit to Celsius, and one to go the other direction. These functions use the standard formulas.

function toCelsius(f) { return (f - 32) * 5 / 9; } and function toFahrenheit(c) { return (c * 9 / 5) + 32; }

Step 2 — Choose what to exportWe want both functions to be available to other files, so we'll use Pattern 1 (export an object). We assign an object to module.exports with both functions as properties.

module.exports = { toCelsius, toFahrenheit };

Step 3 — Create the consumer file (app.js)In a new file called app.js (in the same folder), load the module using require(). The dot-slash tells Node.js to look in the current directory.

const temp = require('./tempConverter');

Step 4 — Use the exported functionsNow temp is the object we exported. We can call temp.toCelsius(212) to convert boiling water's temperature, and temp.toFahrenheit(0) to convert freezing point.

temp.toCelsius(212) → 100 and temp.toFahrenheit(0) → 32

Step 5 — Run the programIn your terminal, navigate to the folder containing both files and run node app.js. Node.js resolves the require path, loads tempConverter.js, executes it, caches the result, and returns the exports object. Your conversions print to the console.

Console output: 100 and 32

💡 Destructuring Shortcut

Instead of const temp = require('./tempConverter'), you can destructure directly: const { toCelsius, toFahrenheit } = require('./tempConverter');. Now you can call toCelsius(212) without the temp. prefix. This is a common pattern in real projects.

SECTION 7

Strengths & Limitations of CommonJS

CommonJS was a groundbreaking solution when it was introduced, and it remains extremely useful in Node.js. However, like any tool, it has trade-offs. Understanding these strengths and limitations helps you know when CommonJS is the right choice—and when you might want an alternative.

Strengths and limitations of CommonJS modules

Aspect	Strength ✓	Limitation ✗
Simplicity	Easy to learn. Just two tools: `require()` and `module.exports`.	No advanced features like named or default exports in one statement.
Loading	Synchronous loading is predictable—code runs in the order you write it.	Synchronous loading blocks execution. Not ideal for browsers where you want to load files in parallel.
Ecosystem	The npm registry has over 2 million CommonJS packages. Massive community support.	Newer packages are increasingly published as ES Modules only, requiring extra configuration.
Caching	Modules are cached after first load, improving performance in large apps.	Cached module state can cause unexpected behavior if a module stores mutable data.
Tree Shaking	N/A—not a strength area.	Bundlers cannot easily remove unused code (tree-shake) from CommonJS modules because exports are dynamic.

✦ KEY TAKEAWAY

CommonJS is like a reliable postal service—it delivers packages one at a time, in order, and the recipient always knows exactly what they're getting. It works perfectly when you're in a single building (a server), but for delivering across many addresses simultaneously (browsers loading many files at once), a faster system like ES Modules can be more efficient.

SECTION 8

CommonJS vs. ES Modules — Looking Ahead

As you grow as a JavaScript developer, you'll encounter ES Modules (ESM), the newer module system built directly into the JavaScript language standard. Knowing how CommonJS compares to ESM helps you navigate modern codebases where both systems coexist.

CommonJS vs. ES Modules comparison

Feature	CommonJS (CJS)	ES Modules (ESM)
Syntax	`require() / module.exports`	`import / export`
Loading	Synchronous (one at a time)	Asynchronous (can load in parallel)
Where it runs	Node.js (server-side)	Browsers and Node.js
Dynamic require	Yes — `require()` can appear inside if-statements	Static `import` must be at the top; dynamic `import()` returns a promise
Tree Shaking	Not supported well	Fully supported — bundlers remove unused exports
File extension	`.js` (default in Node.js)	`.mjs` or `.js` with `"type": "module"` in package.json

You don't need to choose one system and ignore the other. In practice, many Node.js projects still use CommonJS, especially older ones and those that rely on packages from npm. Newer front-end projects tend to use ES Modules. Learning CommonJS first gives you a solid foundation because the core concept of encapsulation and explicit sharing is identical in both systems. Once you're comfortable with require and module.exports, switching to import and export will feel natural.

SECTION 9

Practice Problems

PROBLEM 1 — CONCEPTUAL

In CommonJS, why are the variables you declare inside a module file not automatically available to other files? What mechanism prevents this?

PROBLEM 2 — BASIC CALCULATION

You have a file called utils.js containing: const SECRET = 42; function double(n) { return n * 2; } module.exports = { double }; In app.js, you write const utils = require('./utils');. What is the value of utils.double(5)? What is the value of utils.SECRET?

PROBLEM 3 — INTERMEDIATE

A developer writes the following in greet.js: exports = function(name) { return 'Hello ' + name; }; Then in app.js: const greet = require('./greet'); console.log(greet('Sam')); This throws an error: greet is not a function. Explain why, and fix the bug.

PROBLEM 4 — APPLIED

You're building a simple quiz app with three files: questions.js (stores an array of question objects), scorer.js (has a function that takes an array of answers and returns a score), and app.js (the main file). Write the module.exports line for each module, and write the require() lines in app.js.

PROBLEM 5 — CRITICAL THINKING

Suppose counter.js exports an object: let count = 0; module.exports = { increment() { count++; }, getCount() { return count; } }; Two different files both require('./counter'). File A calls counter.increment() three times. Then File B calls counter.getCount(). What value does File B see? Explain why, referencing how CommonJS caching works.

SUMMARY

Lesson Summary

CommonJS is the module system that powers Node.js, turning each .js file into its own private module. You use module.exports to make functions, objects, or classes available to other files, and require() to load those exports into a consumer file. Everything not explicitly exported stays private, thanks to the module wrapper function that Node.js applies behind the scenes.

The three common export patterns are: exporting an object with multiple functions, exporting a single function, or exporting a class. CommonJS loads modules synchronously and caches them after first load, so the same module is never executed twice. While ES Modules (import/export) are the modern standard, understanding CommonJS is essential because millions of existing packages depend on it. The core lesson—encapsulate your code and share only what's needed—applies to every module system you'll ever use.