CommonJS require and module.exports in Node.js - Deep Dive

Overview - CommonJS require and module.exports

What is it?

CommonJS is a system used in Node.js to organize and share code between files. It uses two main parts: 'require' to load code from other files, and 'module.exports' to make code available to others. This helps break big programs into smaller, manageable pieces. It works by loading and running files when needed.

Why it matters

Without CommonJS, all code would be in one big file, making it hard to read, fix, or reuse. CommonJS solves this by letting developers split code into modules that can be shared easily. This makes building and maintaining programs faster and less error-prone. It also allows using third-party code libraries smoothly.

Where it fits

Before learning CommonJS, you should understand basic JavaScript syntax and how files work on your computer. After mastering CommonJS, you can learn about newer module systems like ES Modules or how to bundle code for browsers. It fits early in the Node.js learning path as the foundation for modular code.

Mental Model

Core Idea

CommonJS lets you split your program into separate files that share code by exporting and requiring modules, like passing tools between workers in a workshop.

Think of it like...

Imagine a workshop where each worker has a toolbox. If one worker needs a hammer, they ask another worker to lend it. 'module.exports' is like putting the hammer in your toolbox to share, and 'require' is like borrowing that hammer from someone else's toolbox.

┌─────────────┐       ┌─────────────┐
│ moduleA.js  │       │ moduleB.js  │
│             │       │             │
│ module.exports ─────▶│ const tool = require('./moduleA')
│ (exports tools)│     │ (borrows tools)│
└─────────────┘       └─────────────┘

Build-Up - 7 Steps

1

Foundation

What is a Module in Node.js

Concept: A module is a single file that contains code which can be reused elsewhere.

In Node.js, every JavaScript file is a module. You can write functions, variables, or objects inside it. By default, these are private to the file unless you explicitly share them.

Result

You understand that code is organized into files called modules, each with its own scope.

Knowing that each file is a separate module helps you think about code as small, independent parts rather than one big block.

2

Foundation

Using module.exports to Share Code

Concept: module.exports is the object that a module returns when another file requires it.

To share something from a module, assign it to module.exports. For example, module.exports = function() { return 'Hello'; } makes that function available to others.

Result

You can make functions or data available outside the module by assigning them to module.exports.

Understanding module.exports is key to controlling what your module shares and what stays private.

3

Intermediate

Loading Modules with require

🤔Before reading on: do you think require loads code once or every time it is called? Commit to your answer.

Concept: require is a function that loads and runs another module, returning what that module exports.

When you call require('moduleName'), Node.js finds the file, runs it if not run before, and returns module.exports from that file. This lets you use code from other files easily.

Result

You can use require to bring in code from other modules and use their exported parts.

Knowing that require runs the module once and caches it explains why changes in the module after loading don't affect the current program.

4

Intermediate

Exports vs module.exports Difference

🤔Before reading on: do you think assigning to exports changes module.exports automatically? Commit to your answer.

Concept: exports is a shortcut to module.exports but assigning exports directly breaks the link.

exports is initially a reference to module.exports. You can add properties to exports like exports.foo = 1, but if you assign exports = something else, it no longer points to module.exports, so the exported value won't change.

Result

You learn to use either module.exports = value or add properties to exports, but not assign exports directly.

Understanding this prevents bugs where your module exports nothing because you overwrote exports instead of module.exports.

5

Intermediate

How require Caches Modules

🤔Before reading on: do you think require loads the same module file multiple times or caches it? Commit to your answer.

Concept: Node.js caches modules after the first load to improve performance and keep state.

When require loads a module, it stores the result in a cache. Later require calls for the same module return the cached exports without re-running the code. This means modules behave like singletons.

Result

You understand that require returns the same object every time for a module, preserving state across requires.

Knowing about caching helps you design modules that maintain state or avoid side effects when loaded multiple times.

6

Advanced

Circular Dependencies in CommonJS

🤔Before reading on: do you think circular requires cause errors or partial exports? Commit to your answer.

Concept: When two modules require each other, Node.js handles it by giving partial exports during loading to avoid infinite loops.

If moduleA requires moduleB and moduleB requires moduleA, Node.js returns an incomplete exports object for the module still loading. This can cause unexpected undefined values if not handled carefully.

Result

You learn to recognize and avoid pitfalls with circular dependencies or design modules to handle partial exports safely.

Understanding circular dependencies prevents bugs that are hard to trace and helps design cleaner module relationships.

7

Expert

Module Wrapping and Execution Context

🤔Before reading on: do you think module code runs in the global scope or a special wrapper? Commit to your answer.

Concept: Node.js wraps each module in a function to provide private scope and module-specific variables.

Behind the scenes, Node.js wraps your module code in a function like (function(exports, require, module, __filename, __dirname) { /* your code */ }). This means variables you declare are local to the module, not global.

Result

You understand why variables don't leak globally and how module variables like exports and require are available automatically.

Knowing about the wrapper function explains module isolation and why you can use require and exports without importing them.

Under the Hood

When you call require('file'), Node.js resolves the file path, reads the file content, and wraps it in a function with parameters exports, require, module, __filename, and __dirname. It then executes this function, passing in objects for exports and module. The module.exports object is what require returns. Node.js caches this result so subsequent requires return the cached exports without re-executing the file.

Why designed this way?

CommonJS was designed to provide a simple, synchronous module system for server-side JavaScript before browsers supported modules. The wrapper function isolates module scope to avoid polluting the global environment. Caching improves performance and allows modules to maintain state. Alternatives like asynchronous or static module systems were not practical for early Node.js use cases.

┌───────────────────────────────┐
│ require('module') called      │
├───────────────────────────────┤
│ 1. Resolve file path           │
│ 2. Check cache                │
│   ├─ If cached: return exports│
│   └─ Else:                    │
│      a) Read file             │
│      b) Wrap in function      │
│         (exports, require,    │
│          module, __filename,  │
│          __dirname)           │
│      c) Execute function      │
│      d) Cache module.exports  │
│      e) Return module.exports │
└───────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does assigning directly to exports change what the module exports? Commit to yes or no.

Common Belief: Assigning a new value to exports changes the exported module.

Reality: Assigning directly to exports breaks the link to module.exports, so the module exports remain unchanged unless module.exports is assigned.

Why it matters: This causes modules to export empty objects unexpectedly, leading to bugs that are hard to diagnose.

Quick: Does require reload the module code every time it is called? Commit to yes or no.

Common Belief: require runs the module code every time it is called, so changes in the module file affect subsequent requires immediately.

Reality: require caches the module after the first load and returns the cached exports on subsequent calls without re-running the code.

Why it matters: Expecting fresh code on every require can cause confusion and bugs when modules maintain state or when hot-reloading is attempted.

Quick: Do circular dependencies cause runtime errors always? Commit to yes or no.

Common Belief: Circular dependencies always cause errors or crashes.

Reality: Node.js handles circular dependencies by providing partial exports during loading, which can cause undefined values but not always errors.

Why it matters: Misunderstanding this leads to ignoring circular dependencies or not designing modules to handle partial exports safely.

Quick: Is CommonJS module code executed in the global scope? Commit to yes or no.

Common Belief: Module code runs in the global scope, so variables declared are global.

Reality: Node.js wraps module code in a function, so variables are local to the module and do not pollute the global scope.

Why it matters: Assuming global scope can cause naming conflicts and misunderstanding of variable visibility.

Expert Zone

1

Modules are cached by resolved absolute path, so requiring the same file via different relative paths creates separate instances.

2

module.exports can be any value (object, function, primitive), but exports is only a shortcut for adding properties to module.exports.

3

The wrapper function provides __filename and __dirname, which are not global but module-specific, enabling modules to know their location.

When NOT to use

CommonJS is synchronous and designed for server environments. For browser code or modern JavaScript, ES Modules (ESM) are preferred because they support static analysis, asynchronous loading, and better tooling. Use ESM for front-end projects or when interoperating with modern JavaScript ecosystems.

Production Patterns

In production, CommonJS modules are often bundled using tools like Webpack or Rollup for browser use. Developers use module.exports to export single functions or objects and require to import dependencies. Circular dependencies are avoided or carefully managed. Caching behavior is leveraged for singleton patterns or shared state.

Connections

ES Modules (ESM)

CommonJS is the older module system; ESM is the modern standard that builds on similar ideas but adds static structure and async loading.

Understanding CommonJS helps grasp ESM's purpose and differences, especially how modules export and import code.

Software Componentization

CommonJS modules are a form of componentization, breaking software into reusable parts.

Knowing how modules isolate code relates to general software design principles of modularity and separation of concerns.

Library Lending in Real Life

Like borrowing books from a library, require borrows code from modules, and module.exports is what the library offers to readers.

This connection shows how sharing resources efficiently is a universal concept beyond programming.

Common Pitfalls

#1 Overwriting exports instead of module.exports

Wrong approach:

exports = function() { return 'Hello'; };

Correct approach:

module.exports = function() { return 'Hello'; };

Root cause:

Misunderstanding that exports is just a reference to module.exports and assigning exports breaks the link.

#2 Expecting require to reload updated module code

Wrong approach:

require('./module'); // expecting fresh code every time

Correct approach:

Restart the Node.js process or clear require cache manually to reload module code.

Root cause:

Not knowing that require caches modules after first load.

#3 Creating circular dependencies without handling partial exports

Wrong approach:

moduleA.js requires moduleB.js and moduleB.js requires moduleA.js without safeguards.

Correct approach:

Refactor code to avoid circular dependencies or design modules to handle partial exports safely.

Root cause:

Ignoring how Node.js handles circular dependencies and partial loading.

Key Takeaways

CommonJS uses module.exports to share code and require to load it, enabling modular programming in Node.js.

Modules are wrapped in a function to provide private scope and module-specific variables like exports and require.

require caches modules after the first load, so subsequent calls return the same exports without re-running code.

Assigning directly to exports breaks the export link; always assign to module.exports to export a value.

Circular dependencies return partial exports during loading, so they must be handled carefully to avoid bugs.