NPM (Node Package Manager)

npm (Node Package Manager) is the default package manager for the Node.js runtime environment. It consists of two main parts:
1. A command-line interface (CLI) used to install, update, and manage project dependencies.
2. An online registry hosting millions of public and private packages (libraries, frameworks, and tools) that developers can share and use.

This guide covers the core concepts, common commands, and best practices for working with npm.

1. Installation and Setup

npm is bundled automatically with Node.js. To use npm, you must install Node.js on your system.

Verification

Once Node.js is installed, open your terminal or command prompt and run the following commands to verify the installation:

# Check Node.js version
node -v

# Check npm version
npm -v

Updating npm

To update npm to the latest stable version, run:

npm install -g npm

2. Initializing a Project

To use npm in a project, you need to initialize it. This process creates a package.json file, which tracks your project's configuration and dependencies.

Navigate to your project directory in the terminal and run:

npm init

You will be prompted to answer several questions (project name, version, description, entry point, etc.).

Quick Initialization

To skip the prompts and generate a default package.json file immediately, use the -y (yes) flag:

npm init -y

Anatomy of package.json

A basic package.json file looks like this:

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "A simple Node project",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "Your Name",
  "license": "ISC",
  "dependencies": {},
  "devDependencies": {}
}

3. Installing Packages

Packages can be installed locally (for a specific project) or globally (for your entire system).

A. Local Installation (Recommended)

Local packages are installed inside the project's node_modules directory and are only accessible within that project.

1. Production Dependencies (dependencies)

These are packages required for the application to run in production (e.g., Express, Lodash, React).

npm install <package-name>
# Shortcut:
npm i <package-name>

2. Development Dependencies (devDependencies)

These are packages only needed during development and testing, not in production (e.g., Jest, ESLint, Nodemon).

npm install <package-name> --save-dev
# Shortcut:
npm i -D <package-name>

B. Global Installation

Global packages are installed in a central system directory and are typically command-line tools (e.g., nodemon, gatsby-cli).

npm install -g <package-name>

Note: Many developers now prefer using npx (covered in Section 7) instead of installing packages globally.

C. Installing All Dependencies

If you download an existing project (e.g., from GitHub) that contains a package.json file but no node_modules folder, you can install all required dependencies by running:

npm install

4. Semantic Versioning (SemVer)

When you install a package, npm adds it to package.json with a version number prefixed by a symbol. npm uses Semantic Versioning (SemVer), which follows the format: MAJOR.MINOR.PATCH.

• MAJOR: Unspecified breaking changes.
• MINOR: New features added in a backwards-compatible manner.
• PATCH: Backwards-compatible bug fixes.

Common Version Prefixes

5. The Role of package-lock.json

When you install packages, npm automatically generates a package-lock.json file.

• What it does: It records the exact dependency tree and the precise version of every package (and its dependencies) installed in your node_modules.
• Why it matters: It ensures that every developer on your team, and your production environment, installs the exact same version of every package, avoiding "it works on my machine" issues.
• Best Practice: Always commit package-lock.json to your version control system (e.g., Git). Do not manually edit this file.

6. Managing Packages

Updating Packages

To see which packages have newer versions available:

npm outdated

To update packages to the latest version allowed by your package.json SemVer constraints:

npm update

Uninstalling Packages

To remove a package from your project and delete it from package.json:

npm uninstall <package-name>
# Shortcut:
npm un <package-name>

7. Running Scripts

The scripts object in package.json allows you to define custom terminal commands.

"scripts": {
  "start": "node server.js",
  "dev": "nodemon server.js",
  "build": "webpack --config webpack.config.js"
}

Executing Scripts

To run most custom scripts, use npm run <script-name>:

npm run dev
npm run build

Special Shorthands

For a few standard script names, you can omit the run keyword:

npm start
npm test

8. What is npx?

npx (Node Package Executor) is a tool bundled with npm (version 5.2.0+). It allows you to execute a package's CLI tool without installing it globally or locally beforehand.

Example

Instead of installing the create-react-app package globally, you can run it once using npx:

npx create-react-app my-new-app

npx temporarily downloads the package, runs the command, and discards it, keeping your system clean.

9. Common npm Commands Quick Reference

The guide was created in June 2026.