Learn the most important npm basic commands every developer should know. This beginner-friendly guide covers project setup, updating and removing packages, global installs, and more to streamline your Node.js projects.

Project Setup

• npm init -> Create a new package.json file interactively.

• npm init -y -> Create package.json with default values.

Installing Packages

• npm install -> Install all dependencies listed in package.json.

• npm install <package> -> Install and add to dependencies.

• npm install <package> --save-dev -> Install and add to devDependencies.

Alias

npm i <package> is the shorthand for npm install <package>.

Updating & Removing Packages

• npm update -> Update all packages according to semantic versioning (semver). It will only update packages within the allowed range (caret ^, tilde ~).

Semantic Versioning (semver):

• Major update - Include breaking changes. Example: react@18.3.0 -> react@19.0.0

• Minor update - Safe updates with new features. Defined by the caret (^). Example: react@^18.3.0 -> react@^18.4.0

• Patch update - Bug fixes and patches. Defined by the tilde (~). Example: react@~18.3.0 -> react@~18.3.1

npm update does not update to a new major version, since those often introduce breaking changes.

The flow of npm update

1. npm update reads the semver range in package.json.
2. Checks npm registry for the newest version allowed by that range.
3. Updates node_modules + package-lock.json accordingly.
4. Leaves package.json untouched (unless use npm update --save to update the version numbers in package.json).

• npm outdated -> Show packages that are outdated.

• npm uninstall <package> -> Remove a package.

Running Scripts

• npm run <script> -> Run a custom script (e.g., npm run dev) that are defined in package.json under "scripts".

"scripts": {
    "dev": "vitepress dev --port 3000",
    "build": "vitepress build",
  },

Here is an example that use npm run dev to execute vitepress dev --port 3000.

Package Info

• npm list -> Show installed packages in the project.

• npm list -g -> Show globally installed packages.

Global Installs

• npm install -g <package> -> Install package globally.

For example, npm install -g @anthropic-ai/claude-code to use it in the terminal (Claude Pro user).

• npm uninstall -g <package> -> Remove a global package.

Maintenance

• npm audit -> Check for security issues.

• npm audit fix --force -> Forces npm to fix security issues.

• npm cache clean --force -> Forces npm clear the cache.

FAQ

What is the alternative way to run npm update?

npx npm-check-updates -u
npm install

Use npx for one-time exeuction without needing to install npm-check-updates globally. npx npm-check-updates -u modifies package.json and then run npm install installs the updated packages.

Reminder

Without -u flag, npm-check-updates only lists which dependencies have newer versions available. With -u flag, it actually modifies your package.json file to bump the versions to the latest releases (within the rules of semver).

How to bypass and update packages that are blocked by their peer dependencies?

1. Force ignore peer dependency conflicts

Run with the --legacy-peer-deps flag:

npm install react@19 react-dom@19 --legacy-peer-deps

Reminder

With --legacy-peer-deps flag, npm install will install packages without considering their peer dependencies. This is often the fastest way forward but you should test your app afterwards.

2. Use overrides in package.json

Add this to your package.json:

{
  "overrides": {
    "react": "19.0.0",
    "react-dom": "19.0.0"
  }
}

Then run:

rm -rf node_modules package-lock.json
npm install

This forces all dependencies to use React 19, even if they ask for React 18.

3. Run npx npm-check-updates and npm install

To reduce conflicts, update other libraries as well. This bumps all deps in package.json to their latest versions, making them less likely to reply on legacy dependecies.