npm Package Manager

npm cheatsheet — install packages, run scripts, publish, audit. npm install, npm run build, npm ci, npm audit fix, npm outdated. Full Node.js package manager reference.

5 min read

What it is

npm is the default package manager for Node.js, used for installing, sharing, and managing JavaScript packages and their dependencies.

Installation

Linux:

sudo apt update
sudo apt install nodejs npm

macOS:

brew install node

Windows:

Download the installer from https://nodejs.org/ and run it. npm is included with Node.js.

Core Concepts

package.json: The manifest file for a Node.js project. It contains metadata about the project, including its name, version, dependencies, scripts, and more.
Dependencies: Packages that your project needs to run. These are listed in package.json.
- dependencies: Packages required for your application to run in production.
- devDependencies: Packages required only for development and testing (e.g., linters, build tools).
node_modules: The directory where npm installs all the project’s dependencies. This directory is usually excluded from version control.
npm registry: A large public database of JavaScript packages hosted on npmjs.com.
SemVer (Semantic Versioning): A versioning scheme (MAJOR.MINOR.PATCH) used for packages, allowing for predictable updates.

Commands / Usage

Project Initialization & Management

npm init Initialize a new Node.js project and create a package.json file.
```
npm init -y
```
Creates a package.json with default values.
npm init <initializer> Initialize a project using a specific initializer (e.g., a framework’s boilerplate).
```
npm init react-app my-react-app
```
Creates a new React application in the my-react-app directory.

Installing Packages

npm install <package-name> Install a package and its dependencies. Adds it to dependencies in package.json and installs it into node_modules.
```
npm install lodash
```
Installs the latest version of lodash.
npm install <package-name>@<version> Install a specific version of a package.
```
npm install react@17.0.2
```
Installs React version 17.0.2.
npm install <package-name> --save-dev (or -D) Install a package as a development dependency. Adds it to devDependencies in package.json.
```
npm install jest --save-dev
```
Installs Jest for testing.
npm install Install all dependencies listed in package.json.
```
npm install
```
Installs all packages defined in node_modules.
npm uninstall <package-name> Remove a package from node_modules and its entry from package.json.
```
npm uninstall express
```
Removes the Express package.
npm install -g <package-name> Install a package globally, making it available as a command-line tool.
```
npm install -g nodemon
```
Installs nodemon globally.
npm uninstall -g <package-name> Uninstall a globally installed package.
```
npm uninstall -g nodemon
```
Uninstalls nodemon.
npm update Update all packages to the latest allowed versions according to package.json’s version ranges.
```
npm update
```
Updates packages like lodash to their latest compatible versions.
npm update <package-name> Update a specific package.
```
npm update lodash
```
Updates lodash to the latest compatible version.

Running Scripts

npm run <script-name> Execute a script defined in the scripts section of package.json.
```
npm run build
```
Runs the build script defined in package.json.
npm start Runs the start script (a common convention).
```
npm start
```
Executes the start command from package.json.
npm test Runs the test script (a common convention).
```
npm test
```
Executes the test command from package.json.

Package Information

npm list List installed packages and their versions.
```
npm list
```
Shows all installed packages in the current project.
npm list -g --depth=0 List globally installed packages.
```
npm list -g --depth=0
```
Shows top-level global packages.
npm view <package-name> Display information about a package from the registry.
```
npm view react versions
```
Shows all available versions of the React package.
npm view <package-name> description Display the description of a package.
```
npm view express description
```
Shows the description of the Express package.

Other Useful Commands

npm clean-install Remove node_modules and reinstall all dependencies based on package.json and package-lock.json. Useful for ensuring a clean slate.
```
npm clean-install
```
Deletes node_modules and reinstalls everything.
npm cache clean --force Clear the npm cache. Sometimes necessary if you encounter strange installation issues.
```
npm cache clean --force
```
Clears the npm cache directory.
npm outdated Check for outdated packages.
```
npm outdated
```
Lists packages that have newer versions available.
npm prune Remove extraneous packages (those not listed in package.json).
```
npm prune
```
Removes any packages in node_modules that aren’t required by package.json.

Common Patterns

Installing a specific version and saving it:
```
npm install moment@2.29.1
```
Globally installing a command-line tool:
```
npm install -g http-server
```
Then run it from any directory:
```
http-server
```

Running a build script defined in package.json:

# Assuming you have "build": "webpack --mode production" in your scripts
npm run build

Executing a script with arguments:
```
# Assuming you have "lint": "eslint ." in your scripts
npm run lint -- --fix
```
The -- separates npm arguments from script arguments.
Installing dependencies from a package-lock.json (ensures reproducible builds):
```
npm ci
```
This command is recommended for CI/CD environments and team collaboration. It’s faster than npm install and strictly adheres to the lock file.
Creating a tarball of your package:
```
npm pack
```
Creates a .tgz file in the current directory for distribution.

Gotchas

Global vs. Local Installs: Packages installed with -g are available system-wide as executables, but are not available to your project’s code directly. Project dependencies should always be installed locally.
package-lock.json: This file is crucial for reproducible builds. It locks down the exact versions of all installed packages, including dependencies of dependencies. Always commit it to version control. npm ci uses this file.
npm update vs. npm install <package>@latest: npm update respects the version ranges in package.json (e.g., ^1.2.3 might update to 1.3.0 but not 2.0.0). npm install <package>@latest will fetch the absolute latest version and update package.json accordingly.
Cache Issues: If you encounter persistent installation errors, try npm cache clean --force.
Permissions Errors (Global Installs): On Linux/macOS, installing globally might require sudo if npm is installed in a system directory. However, it’s often better to configure npm to use a user-owned directory for global installs to avoid permission issues.
npm audit: Use npm audit to check for known security vulnerabilities in your dependencies. npm audit fix attempts to resolve them.