1. Introduction 📦

Every non-trivial Node.js application is built from modules — reusable pieces of code that can be shared, versioned, and composed. This tutorial covers how Node's module systems work, how npm resolves and manages dependencies, and how to publish your own packages.

2. What are Modules? 🧩

A module is simply a file (or set of files) whose code is encapsulated in its own scope. Variables and functions declared inside a module are private by default — they must be explicitly exported to be used elsewhere.

3. CommonJS Modules 📜

CommonJS (CJS) is Node's original module system. Every .js file (without "type": "module") is treated as a CJS module, wrapped automatically in a function that provides require, module, and exports.

function greet(name) {
  return `Hello, ${name}!`;
}

module.exports = { greet };

4. ES Modules 🌐

ES Modules (ESM) are the standardized JavaScript module format, also used in browsers. Node treats .mjs files — or .js files inside a package with "type": "module" — as ESM.

export function greet(name) {
  return `Hello, ${name}!`;
}

5. Core Syntax Reference 🔤

This section covers the individual keywords and functions used across both module systems.

5.1 require()

require() synchronously loads and returns the exports of another module. Results are cached — calling require() on the same path twice returns the same object.

const { greet } = require('./greet');
console.log(greet('Node'));

5.2 module.exports

module.exports is the actual object returned by require(). You can assign to it directly to export a single value (a function, class, or object).

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

5.3 exports

exports is a shorthand reference to module.exports. You can attach properties to it, but reassigning exports directly breaks the reference — always reassign module.exports instead.

exports.add = (a, b) => a + b; // ✅ works

exports = { subtract: (a, b) => a - b }; // ❌ breaks the link to module.exports

5.4 import

import { greet } from './greet.mjs';
import defaultExport from './config.mjs';

5.5 export

export const PI = 3.14159;
export function square(x) {
  return x * x;
}

5.6 Default Exports

A module can have one default export, imported without curly braces and under any name you choose.

export default {
  port: 3000,
  host: 'localhost',
};

5.7 Named Exports

A module can have multiple named exports, each imported by its exact name (or renamed with as).

import { PI, square as sq } from './math.mjs';

5.8 Dynamic Imports

import() is a function-like operator that asynchronously loads a module, returning a Promise. It works in both CJS and ESM contexts and is ideal for code-splitting or conditional loading.

async function loadFeature(flag) {
  if (flag) {
    const { feature } = await import('./feature.mjs');
    feature();
  }
}

6. Resolution 🔍

6.1 Module Resolution

When you require() or import a path, Node follows a specific resolution algorithm to locate the actual file.

6.2 Package Resolution

For bare specifiers like require('express'), Node searches for a node_modules folder in the current directory, then walks up the directory tree until it finds a match or reaches the filesystem root.

6.3 Local Modules

Local modules are files within your own project, referenced with relative paths (./utils, ../lib/db).

6.4 Third-Party Modules

Third-party modules are packages installed from a registry (typically npm) and live inside node_modules.

6.5 Built-in Modules

Node ships with built-in modules like fs, path, http, and crypto. These can be imported with or without the node: prefix (e.g. node:fs), which is recommended to avoid ambiguity with user packages of the same name.

const fs = require('node:fs');
const path = require('node:path');

7. Package Configuration 🗂️

7.1 package.json

package.json is the manifest file describing your project: its name, version, dependencies, scripts, and entry points.

{
  "name": "my-app",
  "version": "1.0.0",
  "type": "module",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "test": "node --test"
  },
  "dependencies": {
    "express": "^4.19.2"
  }
}

7.2 package-lock.json

package-lock.json records the exact version of every installed package (including nested dependencies), ensuring reproducible installs across machines and CI environments.

7.3 Semantic Versioning

Semantic Versioning (SemVer) follows the pattern MAJOR.MINOR.PATCH.

8. Managing Packages 🔧

8.1 Installing Packages

npm install express        # add as a dependency
npm install -D typescript  # add as a devDependency
npm install                # install everything from package.json

8.2 Updating Packages

npm outdated       # see which packages have newer versions
npm update         # update within semver ranges
npm install express@latest  # force upgrade to latest

8.3 Removing Packages

npm uninstall express

8.4 npm Scripts

The scripts field in package.json lets you define shortcuts for common tasks, runnable via npm run <script>.

npm run start
npm run test
npm run build

8.5 Workspaces

Workspaces let you manage multiple related packages (a monorepo) from a single root package.json, sharing a single node_modules and linking local packages together.

{
  "name": "my-monorepo",
  "private": true,
  "workspaces": ["packages/*"]
}

9. Publishing & CLI Packages 🚢

9.1 Publishing Packages

Publishing makes your package available on the npm registry for others to install.

9.2 Creating CLI Packages

A CLI package exposes an executable command. Add a bin field to package.json pointing to a script with a shebang line.

#!/usr/bin/env node

console.log('Hello from my CLI!');

{
  "name": "my-cli",
  "bin": {
    "my-cli": "./bin/cli.js"
  }
}

10. Best Practices ✅

11. Common Mistakes ⚠️

12. Frequently Asked Questions ❓

13. Summary 📝