JavaScript/Node Package Managers The Complete, HandsOn Guide (npm Yarn pnpm Bun)

Every JavaScript project depends on a package manager to download libraries, lock their versions and run scripts. In 2026 there are four serious choices: npm, pnpm, Yarn and Bun. This guide explains what each one does differently, how to pin one per project, safe settings for CI and Docker, and how to move between them.

1. What a package manager does

• Resolves versions. It reads the version ranges in package.json, including your dependencies' own dependencies, and picks exact versions.
• Writes a lockfile. The lockfile records those exact versions, so every machine installs the same tree. Commit it.
• Installs packages into node_modules, or, with Yarn Plug'n'Play, into a cache that Node reads through a loader.
• Runs scripts from package.json and exposes package commands from node_modules/.bin.
• Manages workspaces, several packages in one repository sharing one lockfile.
• Talks to a registry, the public npm registry or a private one, with authentication.

2. The four options at a glance

Yarn 1 (Classic) still works but receives only critical fixes. Keep it for an old project if it works; start new projects on one of the four above. Bun switched from the binary bun.lockb to the text bun.lock in Bun 1.2; if you still have a bun.lockb, run bun install --save-text-lockfile once, commit the new bun.lock and delete the old file.

3. Ideas that apply to every manager

• Lockfile. One per repository, at the root. Never commit two (for example package-lock.json and yarn.lock together).
• Hoisting. npm, Yarn 1 and Bun flatten dependencies into the top node_modules, so your code can accidentally import a package you never declared. pnpm and Yarn PnP block that, which catches "phantom dependencies" early.
• Peer dependencies. A plugin that needs React, for example, declares React as a peer. Mismatched peers cause install warnings or errors; fix the versions rather than forcing the install.
• Overrides. Force a version of a nested dependency, for example to take a security fix: overrides in npm and Bun, pnpm.overrides or the overrides key in pnpm-workspace.yaml in pnpm, and resolutions in Yarn.
• Install scripts. Some packages run code when installed (postinstall). This is the main route supply-chain attacks use; see section 8.

4. npm: the default

npm ships with Node.js, so there is nothing to install. It supports workspaces and overrides.

npm install                 # install and update the lockfile
npm ci                      # clean install from the lockfile only (CI)
npm run build -w apps/web   # run a script in one workspace
npm run build --workspaces --if-present
npm outdated
npm audit

{
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "engines": { "node": ">=22" },
  "packageManager": "[email protected]",
  "overrides": { "some-nested-lib": "2.4.1" }
}

5. pnpm: fast and strict

pnpm keeps one copy of each package version in a global store and hard-links it into projects, which saves a lot of disk and time. Its strict node_modules shows missing dependencies immediately.

# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"

pnpm install
pnpm install --frozen-lockfile     # CI
pnpm -r build                      # every workspace package
pnpm --filter @acme/api test       # one package
pnpm approve-builds                # choose which packages may run install scripts

From pnpm 10, dependencies' install scripts do not run unless you allow them, which is a useful security default. If a native package such as sharp or esbuild fails after installing, it probably needs your approval.

6. Yarn 4: Plug'n'Play and constraints

Modern Yarn is installed per project. By default it uses Plug'n'Play: no node_modules folder, faster installs and strict dependency checks. Tools that expect node_modules may need the fallback linker.

# .yarnrc.yml
nodeLinker: pnp        # or node-modules for maximum compatibility

yarn install --immutable              # CI
yarn workspaces foreach -A run build
yarn up some-lib                      # upgrade a dependency everywhere

Committing .yarn/cache ("zero-installs") lets CI skip the download entirely, at the cost of a larger repository.

7. Bun: speed first

Bun is a JavaScript runtime with a built-in package manager, test runner and bundler. bun install is very fast and works with ordinary package.json projects, even if you run the app on Node.js.

bun install
bun install --frozen-lockfile   # CI
bun run build

Test your native modules and build tools before switching a large existing project.

8. Pin the tool and protect your supply chain

Pin the manager. The packageManager field in package.json names the manager and its exact version, for example "[email protected]" (use the version your team runs; pnpm --version prints it). It tells tools and teammates exactly what to use. Corepack reads it and downloads that version. Corepack is bundled with Node.js 24 and earlier; from Node.js 25 it is no longer bundled, so install it with npm install -g corepack or install the manager directly.

Pin Node.js. Use an active LTS release: Node.js 24, or 22 while it is still supported. Node.js 20 and older have reached end of life. Put the version in .nvmrc or .node-version and in engines; see working with Node.js versions using nvm.

9. CI and Docker recipes

GitHub Actions with pnpm:

- uses: actions/checkout@v5
- uses: actions/setup-node@v5
  with:
    node-version: 24
- run: corepack enable
- run: pnpm install --frozen-lockfile
- run: pnpm -r build

For npm, drop corepack enable, add cache: npm to setup-node and run npm ci. For Yarn, keep corepack enable and run yarn install --immutable. Check the actions' pages for their current major versions.

A multi-stage Docker build with npm:

FROM node:24-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build && npm prune --omit=dev

FROM node:24-slim
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app ./
USER node
CMD ["node", "dist/server.js"]

Copy the lockfile before the source so Docker caches the install layer, and never copy node_modules from your computer into an image: native modules must be built for the image's operating system.

10. Migrating between managers

11. Running this on Domain India

• Shared hosting (cPanel and DirectAdmin). The panel's Node.js tool installs your dependencies with its Run NPM Install button, so npm is the manager to use there. When we checked on 23 September 2026, cPanel offered Node.js 20, 22 and 24; choose 22 or 24. Build on your own computer and upload the result, because large installs and builds can hit the account's memory limits. Jailed SSH is available on every shared hosting plan; it is off by default, so ask support to enable it. Tools available inside the jailed shell vary. See how to deploy a Node.js app on shared hosting.
• App Platform. Node.js apps are detected automatically from package.json; for any other setup, including a specific package manager, provide a Dockerfile. See getting started with the App Platform.
• VPS. A self-managed server where you install Node.js and any package manager yourself.

Frequently asked questions

Ready to deploy? Run a small app on shared hosting, deploy from Git on the App Platform, or take full control on a VPS.