Node.js package managers explained: npm, yarn, pnpm, and beyond

Package management is one of the foundations of modern Node.js development. Every Node project relies on a package manager to install dependencies, manage versions, run scripts, and ensure consistent builds across environments.

In this tutorial, we’ll take a deep dive into Node.js package managers, focusing on:

• What package.json really is
• What package managers exist today
• How npm, Yarn, and pnpm differ internally
• Lock files and why they matter
• Performance, disk usage, and monorepos
• Which package manager to use in different scenarios

This article is intentionally detailed and practical.

1. What Is package.json?

At the heart of every Node.js project is the package.json file. It serves as:

• A manifest of your project
• A list of dependencies
• A place to define scripts
• A source of metadata (name, version, license, etc.)

Example:

{
  "name": "my-node-app",
  "version": "1.0.0",
  "description": "Demo Node.js project",
  "type": "module",
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "jest"
  },
  "dependencies": {
    "express": "^4.19.0"
  },
  "devDependencies": {
    "nodemon": "^3.0.0",
    "jest": "^29.0.0"
  }
}

The package manager reads this file and decides:

• what to install
• from where
• in which version
• and how to resolve conflicts

2. What Is a Package Manager?

A Node.js package manager is responsible for:

• Downloading packages from a registry
• Resolving dependency trees
• Installing packages locally or globally
• Managing lock files
• Running project scripts
• Handling version conflicts

In the Node ecosystem, the registry is usually npmjs.com, regardless of which manager you use.

3. npm (Node Package Manager)

Overview

• Default package manager bundled with Node.js
• Oldest and most widely used
• Improved significantly since npm v7+

Installation

npm comes automatically with Node.js:

node -v
npm -v

Installing Dependencies

npm install express
npm install --save-dev nodemon

package-lock.json

npm generates a package-lock.json file that:

• Locks exact dependency versions
• Ensures reproducible installs
• Records the full dependency tree

Example snippet:

{
  "name": "my-node-app",
  "lockfileVersion": 3,
  "packages": {
    "node_modules/express": {
      "version": "4.19.2",
      "resolved": "...",
      "integrity": "sha512-..."
    }
  }
}

Pros

• Default, no extra setup
• Widely supported
• Good security auditing (npm audit)
• Improved peer dependency handling

Cons

• Slower than alternatives for large projects
• Disk usage can grow quickly
• Historically inconsistent installs (mostly fixed now)

4. Yarn (Classic & Berry)

Yarn was created by Facebook to solve early npm issues.

Yarn Classic (v1)

npm install -g yarn
yarn init
yarn add react

Creates:

• yarn.lock
• node_modules

Yarn Berry (v2+)

Yarn v2 introduced Plug’n’Play (PnP):

• No node_modules folder
• Dependencies resolved via .pnp.cjs

yarn set version berry

yarn.lock

Yarn’s lock file is deterministic and readable:

express@^4.19.0:
  version "4.19.2"
  resolved "https://registry.yarnpkg.com/express/-/express-4.19.2.tgz"

Pros

• Faster installs than npm
• Deterministic dependency resolution
• Great monorepo support
• Advanced constraints and policies

Cons

• Berry can break tools expecting node_modules
• More complex learning curve
• Not always beginner-friendly

5. pnpm (Performant npm)

pnpm is currently the most technically advanced Node package manager.

Core Idea

Instead of duplicating packages, pnpm uses:

• A global content-addressable store
• Hard links and symlinks

Result:

• Massive disk space savings
• Faster installs

Installation

npm install -g pnpm

Installing Dependencies

pnpm install
pnpm add axios

node_modules Structure

pnpm creates a non-flat node_modules structure:

node_modules/
  .pnpm/
  axios@1.6.0/
  lodash@4.17.21/

This prevents phantom dependencies (undeclared imports).

pnpm-lock.yaml

Very strict and deterministic:

dependencies:
  axios:
    version: 1.6.0

Pros

• Fastest installs
• Lowest disk usage
• Enforces correct dependency usage
• Excellent for monorepos

Cons

• Some legacy tools assume flat node_modules
• Slightly more complex mental model

6. Lock Files: Why They Matter

Lock files ensure identical installs across machines.

Never commit multiple lock files in one project.

Bad:

package-lock.json
yarn.lock

Pick one manager per repo.

7. Dependency Types in package.json

dependencies

Runtime dependencies:

"dependencies": {
  "express": "^4.19.0"
}

devDependencies

Development-only tools:

"devDependencies": {
  "eslint": "^9.0.0"
}

peerDependencies

Used mainly by libraries:

"peerDependencies": {
  "react": ">=18"
}

optionalDependencies

Failures won’t break install:

"optionalDependencies": {
  "fsevents": "^2.3.0"
}

8. Version Ranges Explained

"express": "^4.19.0"

• ^ → minor updates allowed
• ~ → patch updates only
• * → anything (dangerous)
• exact: "4.19.2"

Rule of thumb:

• Apps → use ^
• Libraries → be more strict

9. Monorepos and Workspaces

All modern managers support workspaces.

npm

{
  "workspaces": ["packages/*"]
}

Yarn

{
  "workspaces": ["apps/*", "libs/*"]
}

pnpm

packages:
  - apps/*
  - libs/*

pnpm generally performs best for large monorepos.

10. Scripts and Task Running

All managers support scripts:

"scripts": {
  "build": "tsc",
  "lint": "eslint .",
  "dev": "vite"
}

Run with:

npm run dev
yarn dev
pnpm dev

pnpm and yarn allow script shortcuts without run.

11. Security and Auditing

npm

npm audit
npm audit fix

Yarn

yarn audit

pnpm

pnpm audit

All rely on the same vulnerability databases.

12. Which Package Manager Should You Use?

Use npm if:

• You want zero setup
• Teaching beginners
• Small or medium projects

Use Yarn if:

• You want strong workspace tooling
• You already use Yarn in your org
• You like policy enforcement

Use pnpm if:

• You care about performance
• You build monorepos
• You want strict dependency correctness

Personal recommendation for modern projects: pnpm

13. Final Thoughts

Node.js package managers have evolved far beyond simple dependency installers. Today, they influence:

• build speed
• disk usage
• dependency correctness
• team consistency

Understanding their differences makes you a better Node.js engineer, especially at scale.

Please follow and like us: