Node.js Essentials: Modules and npm

Modules are the building blocks of any Node.js application. They let you organize code into reusable pieces, share functionality across files, and leverage thousands of packages from the npm ecosystem. In this tutorial, you will learn how to create modules, import them into other files, and manage dependencies with npm.

Understanding Modules in Node.js

Every JavaScript file in Node.js is treated as a module. When you create a file called greeting.js, it becomes a module that can be imported into other files. Node.js uses the CommonJS module system by default, which provides require() for importing and module.exports for exporting.

Creating Your First Module

Create a new file called greeting.js and add a simple function:

// greeting.js
function sayHello(name) {
  return `Hello, ${name}!`;
}

module.exports = sayHello;

The module.exports statement makes whatever you assign available to other files when they import this module. You can export functions, objects, classes, or any JavaScript value.

Importing a Module

Now create an index.js file in the same directory and import your greeting function:

// index.js
const sayHello = require('./greeting');

console.log(sayHello('World'));
// Output: Hello, World!

When you run node index.js, Node.js loads greeting.js, executes it, and returns whatever was assigned to module.exports. The ./ prefix tells Node.js to look in the current directory.

Exporting Multiple Values

Sometimes you want to export multiple functions or values from a single module. There are two common patterns for this.

Pattern 1: Export an Object

// math.js
const add = (a, b) => a + b;
const subtract = (a, b) => a - b;
const multiply = (a, b) => a * b;

module.exports = {
  add,
  subtract,
  multiply
};

// app.js
const math = require('./math');

console.log(math.add(5, 3));      // Output: 8
console.log(math.multiply(4, 2)); // Output: 8

Pattern 2: Destructuring on Import

You can also destructure directly when importing:

const { add, multiply } = require('./math');

console.log(add(10, 5));       // Output: 15
console.log(multiply(3, 7));   // Output: 21

Both patterns work well. The choice depends on your preference and how many exports you need.

Introduction to npm

npm (Node Package Manager) is the default package manager for Node.js. It comes bundled with Node.js and gives you access to a massive registry of open-source packages. npm also helps you manage your project’s dependencies.

Initializing a New Project

Run npm init in your project directory to create a package.json file:

npm init

This interactive command asks several questions about your project, including the name, version, description, entry point, test command, git repository, keywords, author, and license. You can also use npm init -y to accept all defaults and skip the interactive prompts. This creates a basic package.json file with default values that you can edit later as needed.

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}

The package.json file tracks your project’s metadata and dependencies. Understanding its structure is essential for Node.js development. The main fields include “name” for your project identifier, “version” following semantic versioning (major.minor.patch), “main” pointing to your entry file, and “scripts” defining automation commands. The “dependencies” section lists packages required at runtime, while “devDependencies” lists packages only needed during development.

Installing Packages

Install a package using npm install package-name. For example, to add the popular lodash library:

npm install lodash

This does two things:

1. Downloads the package into a node_modules folder
2. Adds the dependency to package.json

{
  "dependencies": {
    "lodash": "^4.17.21"
  }
}

Using Installed Packages

Once installed, you can import packages just like local modules:

const _ = require('lodash');

const numbers = [1, 2, 3, 4, 5];
console.log(_.sum(numbers));  // Output: 15
console.log(_.shuffle(numbers)); // Output: [3, 1, 5, 2, 4] (random order)

Development Dependencies

Packages you only need during development (like testing frameworks) should be installed as dev dependencies:

npm install --save-dev jest

These appear in a separate section of package.json:

{
  "dependencies": {
    "lodash": "^4.17.21"
  },
  "devDependencies": {
    "jest": "^29.0.0"
  }
}

Understanding node_modules

The node_modules folder contains all packages your project depends on, including their own dependencies. This folder can grow quite large as you install more packages, but you should never commit it to version control. Including node_modules in your repository would bloat the repository size significantly and cause unnecessary conflicts between team members who may have different operating systems or package versions.

Add node_modules to your .gitignore file:

echo "node_modules/" >> .gitignore

Or create a .gitignore file with these contents:

node_modules/

When you clone a repository, run npm install (or npm ci for CI/CD environments) to reinstall all dependencies from the package.json lock file. The lock file ensures everyone on your team gets the exact same versions of all packages, preventing the “it works on my machine” problem.

Summary

You have learned how to create and import modules in Node.js using require() and module.exports. You have also seen how npm helps you manage project dependencies, install packages, and organize your code. These fundamentals are essential for building any Node.js application.

In the next tutorial of this series, you will learn how to work with the file system in Node.js.