The Node Module System

Anything bigger than a toy script needs to be split across files. The Node.js for Beginners series now covers the module system: how files export functionality, how other files import it, how Node finds a module from a require call, and how the newer ES module syntax fits in. Both styles appear in the wild, so you will learn to read and write each.

Why modules exist

Without modules, every file shares one global scope and load order decides everything. Modules give each file its own private scope and force relationships to be declared:

• Encapsulation — internals stay hidden; callers use only what you export.
• Reusability — one utils.js serves every consumer.
• Explicit dependencies — imports tell you at a glance what a file needs.
• Testability — small exported functions are easy to test in isolation.

CommonJS: module.exports and require

CommonJS is Node's original format. The exporting file attaches values to module.exports; the importing file receives exactly that value.

// math.js
function add(a, b) { return a + b; }
function subtract(a, b) { return a - b; }

module.exports = { add, subtract };   // the object consumers will get

// app.js
const { add, subtract } = require('./math');

console.log(add(7, 5));        // → 12
console.log(subtract(7, 5));   // → 2

Expected output:

12
2

• Relative paths need ./ (or ../) — bare names are reserved for packages and built-ins.
• Omitting the extension is fine: Node tries .js, then .json, then .node.
• exports is a shortcut for module.exports — assigning to module.exports itself reassigns the whole export (a classic trap).

How Node resolves a require call

Two properties matter early: modules are cached — the first load runs the file, later loads get the same object — and resolution happens against the file's location, not the shell's working directory. Caching makes shared state possible (a config module really is a singleton) and also explains why changing a file does not change a running process: the old copy stays in memory until you restart. The path rule explains another classic head-scratcher — require('./styles.css') works from a script in the same folder but fails from anywhere else, because "same folder" is relative to the caller.

Built-in modules you will use

const fs = require('fs');
const path = require('path');
const os = require('os');
const http = require('http');

console.log(path.join('logs', 'app.txt'));   // → logs/app.txt (on macOS/Linux)
console.log(os.platform());                  // → darwin

Expected output:

logs/app.txt
darwin

No install step is required for built-ins; they are part of the runtime. Newer code may import them with the node: prefix (require('node:fs')) which makes the origin explicit and guards against a future package name clash.

ES modules: import and export

ES modules (ESM) are the JavaScript standard — the same syntax you use in browsers (see JavaScript Modules). To activate them in Node, set the package type:

{
  "name": "my-app",
  "version": "1.0.0",
  "type": "module"
}

With that flag, .js files in the project are ESM:

// math.mjs or type: module project
export const add = (a, b) => a + b;

// app.js
import { add } from './math.js';
console.log(add(7, 5));   // → 12

Key differences: imports are hoisted and asynchronous in resolution, paths must include the extension (./math.js), __dirname does not exist (use import.meta.dirname), and you cannot dynamically require() — use a dynamic import() expression instead.

Choosing CommonJS or ESM

This course shows both: CommonJS where existing examples use it, ESM where new code benefits. Never mix import and require in the same file mode — Node will throw ReferenceError: require is not defined (or the reverse). Whichever you pick, decide once per package: the choice changes how every file in that folder is parsed, so consistency across the project matters more than the particular winner.

Common mistakes

• Relative path without ./ — require('math') looks in node_modules and fails.
• Reassigning exports — exports = {...} changes a local variable; use module.exports = {...}.
• Mixing module formats in one package — decide per package; type cannot be toggled per file.
• Forgetting the file extension in ESM — import './math' is a syntax Node rejects.
• Assuming a module re-runs each import — caching means shared state; design modules as configuration or as stateless functions, not somewhere in between.

Practice checklist

1. Create greeter.js exporting a function, and call it from main.js with require.
2. Export an object of three helpers and destructure them on import.
3. Log inside a required file twice and prove the caching behaviour with a single printed line.
4. Convert the pair to ESM: add "type": "module", switch to export/import, fix the path.
5. Require a built-in (node:os) and print two pieces of system information.

Modules are how code is organised locally — packages are how it is shared globally. Next: npm and package.json.