npm / yarn / pnpm Cheatsheet — 80+ Commands with Cross-Tool Comparison and Real Pitfalls

Interactively create a package.json by answering prompts (name, version, entry, license, etc.).

⚠ Common pitfall: Defaults assume an open-source library. For an internal app, set `"private": true` immediately so you cannot accidentally publish it to the public registry.

npm init

yarn init

pnpm init

Skip every prompt and generate a default package.json. Fastest way to start a sandbox project.

⚠ Common pitfall: pnpm init has no -y flag because it never prompts — it always writes defaults. Yarn berry (v2+) ignores -y for the same reason.

npm init -y

yarn init -y

pnpm init

Scaffold a new project from a starter (vite, next-app, react-app, astro, etc.). Resolves to `create-<initializer>` and runs it via npx.

⚠ Common pitfall: The package executed is `create-<name>`, NOT `<name>`. `npm init vite` runs `create-vite`. Knowing this lets you read what is actually being downloaded.

npm init vite@latest my-app

yarn create next-app my-app

pnpm create astro@latest

Scaffold from a scoped starter package (e.g. @vitejs/app, @sveltejs/kit).

npm init @vitejs/app my-app

pnpm create @sveltejs/kit my-app

Read a single field out of package.json from the CLI. Handy in scripts and CI.

⚠ Common pitfall: Returns JSON-quoted strings, so `npm pkg get version` gives `"1.2.3"` with quotes. Pipe through `jq -r` or `tr -d \"` to strip.

npm pkg get version

npm pkg get scripts

npm pkg get dependencies.react

Generate a default package.json whose name is already scoped (e.g. @acme/utils). Saves a manual rename before the first publish.

npm init -y --scope=@acme

npm init --scope=@my-org -y

Write any package.json field from the CLI. Use dot paths for nested keys and a trailing [] to push into arrays.

⚠ Common pitfall: For nested objects pass `--json`: `npm pkg set repository.url="git+https://..." --json` keeps the value typed as a string instead of guessing.

npm pkg set type="module"

npm pkg set "keywords[]"="cli"

npm pkg set engines.node=">=20" --json

Auto-correct common package.json problems: normalize the "bin" field, fix the repository URL format, sort known keys. Quiet cleanup before publish.

npm pkg fix

Activate Corepack (ships with Node 16.9+) so the exact yarn / pnpm version pinned in "packageManager" is used automatically, no global install.

⚠ Common pitfall: Pin the version with `packageManager: "pnpm@9.1.0"` in package.json. Without that field Corepack has nothing to enforce and every machine can drift to a different version.

corepack enable

corepack prepare pnpm@9.1.0 --activate

"packageManager": "pnpm@9.1.0"

Install every dependency listed in package.json. Reads (or creates) the lock file. The most-typed command in JS.

⚠ Common pitfall: A bare `install` will UPDATE the lock file if package.json drifted ahead. In CI use `npm ci` / `yarn install --frozen-lockfile` / `pnpm install --frozen-lockfile` to fail on drift instead of silently mutating.

npm install

npm i

yarn

pnpm i

Add a runtime dependency. Writes to "dependencies" in package.json and updates the lock file.

⚠ Common pitfall: npm uses `install`/`i`; yarn and pnpm use `add`. Mixing them up does not error — yarn install <pkg> silently ignores the package name and installs everything.

npm install react

yarn add react

pnpm add react

Add a development-only dependency (typescript, eslint, vitest). Writes to "devDependencies".

⚠ Common pitfall: -D matters: production installs (`npm ci --omit=dev`) skip devDependencies. Put your build tools in -D, runtime libs in regular deps.

npm install typescript -D

yarn add eslint -D

pnpm add vitest -D

Install a CLI globally so it lives on $PATH (e.g. pnpm, vercel, typescript).

⚠ Common pitfall: Yarn berry (v2+) removed `yarn global` entirely — use `yarn dlx` for one-shots or install via npm. Globals are also the #1 source of "works on my machine" version mismatches.

npm install -g pnpm

yarn global add typescript  # classic only

pnpm add -g vercel

Pin a specific version, a range, or a dist-tag. Use `@latest` to force the newest, `@next` for prereleases.

⚠ Common pitfall: A bare `@latest` does NOT update an already-installed package unless you also use `--save` (npm) or pass an explicit higher range. Use `npm update <pkg>` to bump within the existing range.

npm install react@18.2.0

yarn add lodash@^4.17.0

pnpm add next@latest

Clean Install. Wipes node_modules, then installs strictly from the lock file. Fails if package.json and lock disagree. The right command for CI.

⚠ Common pitfall: npm ci REQUIRES a package-lock.json — fails immediately if missing. Yarn berry uses `yarn install --immutable` (newer alias for --frozen-lockfile).

npm ci

yarn install --frozen-lockfile

pnpm install --frozen-lockfile

Install without the leading ^ / ~ so package.json pins an exact version. Useful when you want byte-identical installs across machines.

⚠ Common pitfall: Exact pins LOCK you out of patch fixes. For apps prefer the lock file to enforce reproducibility; let semver float in package.json so `npm update` works.

npm install react --save-exact

pnpm add lodash --save-exact

Add to "optionalDependencies". Install failures (e.g. native compile fail) are ignored instead of aborting.

npm install fsevents -O

pnpm add fsevents -O

Force install as production "dependencies" (default for npm anyway — explicit form mostly useful when overriding a previous -D).

npm install react -P

pnpm add react -P

Disable npm 7+ automatic peer-dep installation and use npm 6 behavior — useful when a transitive peer dep conflicts.

⚠ Common pitfall: A frequently-needed escape hatch when upgrading old codebases. Yarn / pnpm have their own peer policies — yarn ignores by default, pnpm errors loudly.

npm install --legacy-peer-deps

npm install react@18 --legacy-peer-deps

Re-fetch the package even if the cache says it is intact and override conflict warnings. Last-resort sledgehammer.

⚠ Common pitfall: pnpm --force ALSO wipes node_modules and re-extracts everything — much heavier than npm/yarn. Try `pnpm install` first before reaching for it.

npm install --force

pnpm install --force

Install directly from a git repository (a fork, an unreleased branch, a private repo).

⚠ Common pitfall: Lock file pins the commit hash, not the branch — re-running `install` will NOT pick up new commits unless you re-add. Pin with #commit for reliability.

npm install github:user/repo

yarn add git+https://github.com/user/repo.git#v1.2.3

pnpm add github:user/repo#main

Install from a local folder or tarball. Useful for testing a publish candidate before going live.

⚠ Common pitfall: pnpm copies the folder into the store; if you edit the source, you must re-install. Use `link:` (or `pnpm link`) instead for live development.

npm install file:../my-lib

pnpm add link:../my-lib

npm install ./my-lib-1.0.0.tgz

Skip devDependencies. The right install command for a production Docker image or deploy.

⚠ Common pitfall: Old npm used `--production` which set NODE_ENV=production as a side effect. `--omit=dev` is the modern flag (npm 7+) and is the explicit form to prefer.

npm install --omit=dev

npm ci --omit=dev

pnpm install --prod

Skip postinstall / preinstall / install scripts. Critical security hardening when auditing a new dependency.

⚠ Common pitfall: Postinstall scripts have been the vector for many supply-chain attacks. Set `ignore-scripts=true` in .npmrc by default, then opt back in for trusted packages.

npm install --ignore-scripts

# .npmrc default:
ignore-scripts=true

pnpm install --ignore-scripts

The everyday shorthand for install. Bare `yarn` (no subcommand) means install; `npm i` and `pnpm i` are the documented aliases.

npm i

yarn

pnpm i

Install by dist-tag instead of a version number. `@next` / `@beta` / `@canary` pull prereleases; `@latest` forces the newest stable.

⚠ Common pitfall: A tag is a moving pointer, not a frozen version. The lock file still records the concrete version it resolved to, so re-installs are reproducible even though the tag may have moved.

npm install next@canary

yarn add react@beta

pnpm add vite@next

Install a package under a different local name (aliasing). Lets two major versions of the same library coexist.

⚠ Common pitfall: Useful for gradual migrations: `npm i lodash4@npm:lodash@4` and `lodash3@npm:lodash@3` both resolve, so you migrate call sites one by one.

npm install react18@npm:react@18

yarn add vue2@npm:vue@2

pnpm add lodash-es@npm:lodash-es@4

Control the version-range prefix written to package.json. `~` allows patch updates only, `^` allows minors, empty string pins exact.

⚠ Common pitfall: Set it once in .npmrc with `save-prefix="~"` so the whole project picks the same policy instead of relying on each developer to remember the flag.

npm install react --save-prefix="~"

# .npmrc
save-prefix=~

Install a package into node_modules WITHOUT writing it to package.json. Handy for a one-off experiment you do not want to commit.

⚠ Common pitfall: Because it leaves no trace in package.json, a later `npm ci` wipes it. Treat --no-save installs as throwaway, never as a dependency you rely on.

npm install some-tool --no-save

npm install ./local-tgz --no-save

Use the local cache whenever possible and only hit the network for what is missing. Faster installs on flaky connections.

⚠ Common pitfall: `--offline` is the stricter sibling: it NEVER touches the network and fails if anything is uncached. Use --offline in air-gapped CI, --prefer-offline for day-to-day speed.

npm install --prefer-offline

npm ci --prefer-offline

pnpm install --offline

Explicitly install optionalDependencies (they install by default, but `--omit=optional` or CI configs may have switched them off).

⚠ Common pitfall: The classic case is a Linux CI installing on a Mac dev box: platform-specific optionals like `@rollup/rollup-linux-x64-gnu` differ. Commit the lock file generated on the target OS or use `--omit=optional` carefully.

npm install --include=optional

npm install --omit=optional

Flatten the dependency tree: move duplicated sub-dependencies up so a single shared copy satisfies multiple dependents. Shrinks node_modules.

⚠ Common pitfall: Run after a big upgrade to clear redundant duplicate versions the resolver left behind. yarn berry has it built in; npm 7+ also de-dupes automatically on most installs.

npm dedupe

npm ddp

pnpm dedupe

Install strictly from the cache with zero network access. Fails loudly if any package is not already cached. The reproducible-build / air-gap install.

npm install --offline

pnpm install --offline

Run a script defined under "scripts" in package.json (build, dev, lint, custom names — anything).

⚠ Common pitfall: Yarn lets you omit `run` for any script; pnpm allows it too EXCEPT when the name clashes with a builtin (`install`, `add`, `test`). Then you need `pnpm run <script>`.

npm run build

yarn build

pnpm dev

Shortcut for `npm run start`. If no start script exists, npm falls back to `node server.js`.

npm start

yarn start

pnpm start

Shortcut for `npm run test`. Treated specially by all three tools (no need for `run`).

npm test

yarn test

pnpm test

Pass extra arguments to the underlying command. npm requires `--` to separate; yarn / pnpm forward args automatically.

⚠ Common pitfall: Forgetting `--` in npm silently sends the flags to npm itself, not to your script. The classic "why is my --watch flag ignored" bug.

npm run build -- --watch

yarn test --coverage

pnpm lint --fix

Edit package.json from the CLI without opening it. Adds or replaces a script entry. Modern npm 7+.

⚠ Common pitfall: Yarn / pnpm have no native equivalent — they suggest editing the JSON directly. `npm pkg` works in any project regardless of package manager.

npm pkg set scripts.build="vite build"

npm pkg set scripts.lint="eslint ."

npm pkg get scripts

Remove a script entry from package.json via the CLI. Pairs with `npm pkg set`.

npm pkg delete scripts.test

npm pkg delete scripts.prepublish

With no script name, lists every script defined in package.json.

npm run

yarn run

pnpm run

Run a binary from an npm package WITHOUT installing it permanently. Perfect for one-shots (create-vite, knip, depcheck).

⚠ Common pitfall: npx caches the downloaded package — fast next time. Yarn dlx / pnpm dlx always re-download for "fresh" each time. Use the right one based on your CI cost vs reproducibility tradeoff.

npx create-vite my-app

yarn dlx knip

pnpm dlx serve dist

Run a binary from a LOCAL node_modules without typing `./node_modules/.bin/<cmd>`. The non-network sibling of npx/dlx.

⚠ Common pitfall: npx falls back to download if the binary is not found locally. `npm exec` errors instead — predictable for CI.

npm exec vitest

pnpm exec eslint .

yarn exec prettier --write .

Lifecycle hooks: a script named `prebuild` runs automatically before `build`, `postbuild` runs after. No setup needed.

⚠ Common pitfall: pnpm DISABLES pre/post auto-execution by default (since pnpm 7) — set `enable-pre-post-scripts=true` in .npmrc if you rely on them.

"prebuild": "rm -rf dist"

"postinstall": "patch-package"

# pnpm:
enable-pre-post-scripts=true

Chain scripts with shell operators inside a script value. `&&` runs sequentially and stops on first failure; `&` runs in the background.

⚠ Common pitfall: `&&` is not cross-platform for parallel work — use `npm-run-all` (run-s / run-p) or `concurrently` so Windows behaves the same as macOS/Linux.

"ci": "npm run lint && npm run test && npm run build"

npx run-p lint test

npx concurrently "npm:dev:*"

Suppress npm’s own log header and the lifecycle noise, leaving only the script’s real output. Great when piping output to another command.

⚠ Common pitfall: Alias `-s`. To go fully quiet set `loglevel=silent` in .npmrc. Without --silent, `npm run get-version` pipes npm’s banner into your downstream command and breaks parsing.

npm run env --silent

npm run --silent version-info | jq

pnpm -s build

The long form of `npm run`. `run` is just an alias of `run-script`. Knowing this helps when reading old docs or generated scripts.

npm run-script build

npm run-script test

Force npx to use ONLY a locally installed binary and never download. Fails fast if the binary is not in node_modules.

⚠ Common pitfall: The opposite, `npx --yes <cmd>`, auto-confirms a download without the y/N prompt — convenient in CI but a supply-chain footgun if the package name has a typo.

npx --no-install eslint .

npx --yes prettier --check .

pnpm exec tsc --noEmit

Open a subshell inside an installed dependency’s folder and run a command there. Useful for inspecting or rebuilding a single package.

npm explore esbuild -- npm run build

npm explore sharp -- node -p "process.platform"

Remove a package from node_modules and from the corresponding section of package.json + lock file.

⚠ Common pitfall: Aliases: `npm un`, `npm rm`, `npm r`. yarn uses `remove` (or `rm`); pnpm accepts both `remove` and `rm`. Trying `npm remove` works too — it is aliased.

npm uninstall react

yarn remove eslint

pnpm remove typescript

Remove a globally-installed CLI.

npm uninstall -g create-react-app

pnpm remove -g vercel

Remove "extraneous" packages — anything in node_modules but not in package.json. Cleans up after deleting deps manually.

⚠ Common pitfall: pnpm node_modules has a different structure (symlinks to a content-addressable store) — `pnpm prune` does the equivalent but the disk savings look different from npm.

npm prune

npm prune --production

pnpm prune

The nuclear "have you tried turning it off and on again" of npm. Delete node_modules and the lock file, then re-install. Last resort, not first.

⚠ Common pitfall: Deleting the lock file LOSES your reproducibility — every transitive dep can move within its range. Try `npm install` first, then `npm ci`, only then nuke.

rm -rf node_modules package-lock.json && npm install

rm -rf node_modules pnpm-lock.yaml && pnpm install

Update every dependency to the newest version that still satisfies the semver range in package.json. Does NOT change the range itself.

⚠ Common pitfall: This does NOT cross major-version boundaries. To break out of "^1.x", you must edit the range manually or use `npm-check-updates` (ncu) / `yarn upgrade-interactive --latest`.

npm update

yarn upgrade

pnpm update

Update a single dependency to the newest version within its current range.

npm update react

yarn upgrade lodash

pnpm update next

List every dependency where current < wanted < latest, so you can see what would change before running an update.

⚠ Common pitfall: "Wanted" = max within current semver range. "Latest" = absolute newest tag. The gap between them is the major-version upgrade you have to opt into.

npm outdated

yarn outdated

pnpm outdated

Third-party tool that edits package.json to the latest versions (jumps majors). Then run install to apply.

⚠ Common pitfall: ncu only edits package.json — it does NOT install. Run `npm install` (or yarn/pnpm) afterwards. Also: review the diff before committing — majors often break.

npx npm-check-updates

npx ncu -u

npx ncu -i  # interactive

Print the installed dependency tree. Shows what is actually in node_modules, with versions.

⚠ Common pitfall: On big projects the tree is huge — use `npm ls <pkg>` to find one, `npm ls --depth=0` for top-level only. pnpm has a much flatter, more readable output by default.

npm ls

npm ls react

npm ls --depth=0

pnpm list -r

Show WHY a package is in node_modules — which dependency chains pulled it in. Essential for tracking phantom deps.

⚠ Common pitfall: npm 7+ ships `npm explain`; older npm uses `npm ls <pkg>` for the same info but less detailed. yarn/pnpm `why` is much more readable.

npm explain lodash

yarn why lodash

pnpm why lodash

Update within the range AND rewrite package.json so the new minimum version is recorded. Plain `npm update` (npm 7+) already saves; older npm needed --save.

npm update --save

npm update react --save

Yarn’s interactive upgrade picker: shows each outdated dep with current/wanted/latest and lets you select which to bump with the keyboard.

⚠ Common pitfall: Classic stays within ranges; add `--latest` to cross majors. npm has no native equivalent — use `npx npm-check -u` or `npx taze` for the same UX.

yarn upgrade-interactive

yarn upgrade-interactive --latest

npx taze -I

The reliable way to jump a single dependency to its newest version AND update the range in package.json (unlike `npm update`, this crosses majors).

⚠ Common pitfall: This is what most people actually want when they say "update react" — `npm update react` keeps you on the old major if your range is `^17`. Use `@latest` to break out.

npm install react@latest

pnpm add next@latest

yarn add typescript@latest -D

List only top-level (directly declared) dependencies with their installed versions. The readable everyday view of "what did I actually add".

npm ls --depth=0

npm ls -g --depth=0

pnpm list --depth=0

Print the FULL nested dependency tree, every level deep. Heavy, but the way to trace a deeply-buried transitive version.

npm ls --all

npm ls --all 2>/dev/null | grep lodash

pnpm list --depth=Infinity

Create a .tgz tarball of your package (exactly what `publish` would upload) without uploading it. The right way to dry-run a publish.

⚠ Common pitfall: Inspect the tarball before publishing! `tar -tzf my-pkg-1.0.0.tgz` shows every file. Catch .env / dist artifacts / .git that escaped your `files` / .npmignore config.

npm pack

npm pack --dry-run

yarn pack -f my-pkg.tgz

Upload the package to the registry. Reads name + version from package.json. Public by default for unscoped, private by default for scoped.

⚠ Common pitfall: Scoped packages need `--access public` on first publish (or registry refuses with 402). Once a version is published, you CAN NOT republish the same version — bump it first.

npm publish

npm publish --access public

npm publish --tag beta

Bump version in package.json AND create a git tag in one step (e.g. v1.2.3). Standard pre-publish dance.

⚠ Common pitfall: Requires a clean working tree by default — commit or stash first, or use `--allow-same-version` / `--no-git-tag-version` to bypass.

npm version patch

npm version minor -m "Release v%s"

pnpm version major

Tag a published version with a label (latest, next, beta, lts). Users can install by tag with `<pkg>@<tag>`.

⚠ Common pitfall: `latest` is the default install tag — point it carefully. To publish a beta WITHOUT updating `latest`, always publish with `--tag beta`.

npm dist-tag add my-pkg@1.2.3 latest

npm dist-tag ls my-pkg

npm dist-tag rm my-pkg beta

Remove a published version from the registry. Heavily restricted — only allowed within 72 hours of publishing and only if no other package depends on it.

⚠ Common pitfall: After 72h use `npm deprecate <pkg>@<version> "<msg>"` instead — it leaves the package installable but shows a warning. Unpublishing causes downstream breakage and the left-pad fiasco of 2016.

npm unpublish my-pkg@1.0.0

npm deprecate my-pkg@1.0.0 "Use v2.0 instead"

Show which npm user you are currently logged in as. First thing to check before a publish goes sideways.

npm whoami

yarn npm whoami

pnpm whoami

Log in to the registry. Required before publishing. Modern npm uses a web flow; old flow uses username/password/email.

⚠ Common pitfall: For private registries always include `--registry <url>` or set `.npmrc` per project — otherwise credentials go to the public registry by mistake.

npm login

npm login --registry=https://registry.example.com

npm logout

Simulate a publish: shows the tarball contents, calculates the version, and stops before the upload. The safety belt for a clean release.

⚠ Common pitfall: Combine with `npm publish --provenance` (on GitHub Actions) to attach a signed build attestation — visible on the package page.

npm publish --dry-run

npm publish --provenance --access public

pnpm publish --dry-run --no-git-checks

Provide a TOTP one-time code for 2FA-protected publishing inline (no interactive prompt). Required in CI when 2FA is enforced.

⚠ Common pitfall: Better than --otp: use a granular access token with publish scope from your npm account settings, store it as NODE_AUTH_TOKEN. No human in the loop.

npm publish --otp=123456

# CI:
NODE_AUTH_TOKEN=$NPM_TOKEN npm publish

Bump to the next prerelease (1.2.0 → 1.2.1-beta.0) and tag it. Repeat to walk beta.0 → beta.1 before the real release.

⚠ Common pitfall: Pair with `npm publish --tag beta` so the prerelease does NOT become the default `latest`. The two flags are separate: `version` bumps the number, `publish --tag` controls the install pointer.

npm version prerelease --preid=beta

npm version prerelease --preid=rc

npm publish --tag beta

Set an exact version explicitly instead of bumping by semver level. Useful when aligning to an external version scheme or a release plan.

⚠ Common pitfall: Skipping versions (1.0.0 → 2.5.0) confuses consumers and changelog tools. Only do it deliberately, e.g. aligning a fork to upstream’s numbering.

npm version 2.0.0-rc.1

npm version 1.4.2 --no-git-tag-version

Mark one or more published versions as deprecated. They stay installable but every install prints your warning message. The humane alternative to unpublish.

⚠ Common pitfall: Pass an empty string to UN-deprecate: `npm deprecate my-pkg@1.0.0 ""`. The range can cover many versions at once, e.g. `my-pkg@"<2.0.0"`.

npm deprecate my-pkg@"<2.0.0" "v1 is EOL, upgrade to v2"

npm deprecate my-pkg@1.0.0 ""

Change a scoped package between public and private after the fact (modern replacement for `npm access public`). Requires owner rights.

⚠ Common pitfall: Going from private to public is irreversible in spirit — once code is public, assume it was scraped. `npm access list packages` shows what you own.

npm access set status=public @my/utils

npm access list packages

npm access get status @my/utils

Add a co-maintainer who can publish new versions of a package. Pairs with `npm owner rm` and `npm owner ls`.

⚠ Common pitfall: For orgs prefer team-based access over per-user owners — `npm access grant read-write @org:team <pkg>` scales better than adding people one at a time.

npm owner add alice my-pkg

npm owner ls my-pkg

npm owner rm bob my-pkg

Publish under a non-default dist-tag so the new version does NOT become `latest`. The correct way to ship a beta without disrupting stable users.

⚠ Common pitfall: Forgetting `--tag` on a prerelease publish is the #1 way to accidentally serve a broken beta to everyone running `npm install <pkg>`. Always tag prereleases.

npm publish --tag next

npm publish --tag canary --access public

pnpm publish --tag beta --no-git-checks

Enable monorepo mode. npm/yarn use a "workspaces" array in the root package.json; pnpm uses a separate pnpm-workspace.yaml.

⚠ Common pitfall: pnpm separates this on purpose so the file works with any tool. Yarn berry adds nohoist / packageExtensions options npm/pnpm do not have.

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

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

packages:
  - "packages/*"

Add a dependency to a specific workspace package, not the root.

⚠ Common pitfall: A common mistake: bare `npm install <dep>` at the root adds it to the ROOT package.json, not a workspace. Always pass `-w <name>` (npm) or `--filter <name>` (pnpm).

npm install lodash -w @my/web

yarn workspace @my/web add lodash

pnpm add lodash --filter @my/web

Run a script in a specific workspace from anywhere in the monorepo.

npm run build -w @my/web

yarn workspace @my/api start

pnpm --filter @my/web build

Run a script in EVERY workspace that has it. `pnpm -r` is the most powerful (parallel, topological order).

⚠ Common pitfall: npm runs sequentially. pnpm -r runs in parallel by default — add `--workspace-concurrency=1` if your scripts have race conditions.

npm run build --workspaces

pnpm -r build

pnpm -r --parallel dev

Run a script across all workspaces but SKIP packages that do not define it (instead of erroring).

npm run test --workspaces --if-present

pnpm -r --if-present test

Inside package.json depend on another local workspace with `"@my/utils": "workspace:*"`. Resolved to the local version at install time.

⚠ Common pitfall: At publish time these get rewritten to actual semver ranges. yarn berry / pnpm handle this automatically; npm 7+ also supports the protocol but rewriting is less mature.

"@my/utils": "workspace:*"

"@my/utils": "workspace:^"

"@my/utils": "workspace:~1.2.3"

Target multiple workspaces in one command. pnpm filters compose (--filter A --filter B), and accept globs / dependency selectors like `...^@my/api`.

⚠ Common pitfall: `pnpm --filter "...@my/api"` means "@my/api AND everything it depends on" (build order matters). `pnpm --filter "@my/api..."` is the reverse (dependents).

pnpm --filter @my/web --filter @my/api build

pnpm --filter "./packages/**" test

pnpm --filter "...@my/api" build

Install all dependencies for every workspace plus the root in one pass. The single command to bootstrap a fresh monorepo checkout.

⚠ Common pitfall: In npm you sometimes need `--workspaces`; yarn/pnpm install everything by default. pnpm additionally symlinks cross-workspace deps so local packages resolve without a build step.

npm install --workspaces --include-workspace-root

pnpm install

yarn install

Run an arbitrary binary inside one workspace’s context (its node_modules/.bin). Different from running a named script.

npm exec -w @my/web -- vitest run

pnpm --filter @my/api exec prisma generate

yarn workspace @my/web exec tsc --noEmit

pnpm dependency selector: `<pkg>...` means the package AND all packages that depend on it; `...<pkg>` means the package AND all its dependencies.

⚠ Common pitfall: Add `[<ref>]` to scope by git changes: `pnpm --filter "...[origin/main]" build` only builds packages touched since main. The killer feature for fast monorepo CI.

pnpm --filter "@my/ui..." build

pnpm --filter "...@my/ui" test

pnpm --filter "...[origin/main]" build

Run a raw shell command in every workspace package, in topological (dependency) order. More flexible than `-r <script>` because it is not tied to package.json scripts.

pnpm -r exec rm -rf dist

pnpm -r exec pwd

pnpm -r --parallel exec tsc --noEmit

pnpm catalogs: declare a shared version once in pnpm-workspace.yaml, reference it as `"react": "catalog:"` in every package. One place to bump a version across the whole monorepo.

⚠ Common pitfall: Solves "every package pins react slightly differently" drift. Requires pnpm 9.5+. Named catalogs (`catalog:react18`) let you run multiple version lines side by side.

# pnpm-workspace.yaml
catalog:
  react: ^18.3.0

"react": "catalog:"

"react": "catalog:react18"

Two-step: in the source package run `link` to create a global symlink; in the consumer project run `link <pkg>` to point at it. Great for testing libraries in a real app.

⚠ Common pitfall: Causes mysterious peer dep warnings because the linked package brings its OWN node_modules. Modern alternative: pnpm `workspace:*` or yarn `portal:` protocol — no global state.

# in lib/
npm link
# in app/
npm link my-lib

pnpm link --global

pnpm link /abs/path/to/lib

Undo a `link`. Always re-run `install` after unlinking so the real registry version is restored.

⚠ Common pitfall: Forgetting the post-unlink install leaves an empty hole in node_modules and the app breaks at runtime, not install time.

npm unlink my-lib

npm install

pnpm unlink --global my-lib

List every package currently linked globally on your machine. Useful when you have lost track of where the symlink graph points.

npm ls -g --link

pnpm list -g

Yarn berry’s answer to `npm link`: `"my-lib": "portal:../my-lib"` symlinks a local folder WITH its own dependency resolution, avoiding the duplicate-react class of link bugs.

⚠ Common pitfall: `link:` (also available) does NOT pull the target’s dependencies; `portal:` does. Use portal for a real package you are co-developing, link for a plain folder of files.

"my-lib": "portal:../my-lib"

"my-lib": "link:../shared"

pnpm’s two-step global link: run `pnpm link --global` in the library, then `pnpm link --global <pkg>` in the consumer. Or skip globals entirely with a direct path link.

⚠ Common pitfall: Direct `pnpm link <path>` (no --global) is cleaner — it writes a `link:` dependency to package.json scoped to that project, leaving no machine-wide global state to clean up later.

# in lib/
pnpm link --global

# in app/
pnpm link --global my-lib

pnpm link ../my-lib

Wipe the local package cache. Use when a corrupt download keeps causing install failures.

⚠ Common pitfall: npm prints "as of npm@5, the npm cache self-heals" — true, but rare cases still need `--force`. pnpm `store prune` only removes packages no project references, much safer.

npm cache clean --force

yarn cache clean

pnpm store prune

Verify the integrity of cached entries and remove garbage. Lighter than clean — does not nuke valid cache.

npm cache verify

Print the directory where the cache lives. Useful for debugging disk-space surprises.

npm config get cache

yarn config get cacheFolder

pnpm store path

Write a config value (registry URL, cache dir, save-prefix) into the user .npmrc / .yarnrc / .npmrc.

⚠ Common pitfall: Project-level .npmrc overrides user-level. CI commonly fails because a project .npmrc points at a private registry the runner cannot reach. Check both levels.

npm config set registry https://registry.npmmirror.com

npm config set save-exact true

pnpm config set store-dir /data/.pnpm-store

Dump every effective config value with its source (default / cli / env / user / project). Essential for debugging "why is my registry wrong".

npm config list

npm config list -l  # include defaults

pnpm config list

Open the user .npmrc in $EDITOR for direct editing. Faster than `config set` for multiple changes.

npm config edit

EDITOR=vim npm config edit

Print which registry installs currently target. First diagnostic when a package "does not exist" or installs the wrong build.

⚠ Common pitfall: A leftover `registry=https://some-mirror` in .npmrc is the usual culprit for "works at home, 404 at the office". Compare `npm config get registry` against the public default.

npm config get registry

npm config set registry https://registry.npmjs.org

pnpm config get registry

Write config to the global (machine) .npmrc instead of the per-user one. Use --location=project to scope it to the current repo’s .npmrc.

⚠ Common pitfall: npm 9 renamed `--global` to `--location=global` for config. Three locations exist: project, user, global — and they layer in that precedence order.

npm config set fund false --location=project

npm config set //registry.npmjs.org/:_authToken=$TOKEN --location=user

Remove a config key so the value falls back to its default. The clean way to undo a `config set` that broke installs.

npm config delete registry

npm config delete proxy

pnpm config delete store-dir

Check the content-addressable store for packages whose files were modified or are missing. Verifies the integrity of pnpm’s shared global store.

⚠ Common pitfall: If a project mysteriously fails to resolve, run `pnpm store status` then `pnpm install --force` to re-link from a verified store. Much cheaper than nuking node_modules.

pnpm store status

pnpm store path

pnpm store prune

Note on cache cleaning: since npm 5 the cache self-heals and corruption is rare. Reach for `npm cache verify` first; `clean --force` is the heavier last step.

npm cache verify

npm cache clean --force

Scan installed packages for known vulnerabilities and print a severity report.

⚠ Common pitfall: CI gating on audit is fragile — new CVEs land daily and you cannot fix every transitive dep. Filter by `--audit-level=high` and use overrides for the ones you accept.

npm audit

npm audit --audit-level=high

pnpm audit --prod

Try to auto-resolve vulnerabilities by upgrading dependencies within current ranges (or with --force across majors).

⚠ Common pitfall: `audit fix --force` will jump majors — your CI tests must be solid or you break prod. Always commit the lock file change separately to make rollback easy.

npm audit fix

npm audit fix --force

pnpm audit --fix

List dependencies that ask for funding (with their donation URLs). Mostly informational, not a security concern.

⚠ Common pitfall: Set `--no-fund` in CI to silence the message every install spits out. Add to .npmrc: `fund=false`.

npm fund

npm install --no-fund

pnpm fund

Print package metadata: latest version, all versions, dependencies, license, repository — without installing.

npm view react

npm view react versions

pnpm view next dist-tags

Search the registry by keyword. Honestly: the npmjs.com website is usually better.

npm search react state-management

pnpm search vite plugin

List every published version of a package as JSON. Useful to confirm a version exists before pinning it, or to find the latest patch of an old major.

npm view react versions --json

npm view next@"^13" version

pnpm view vite versions

Show the dist-tag → version map for a package: what `latest`, `next`, `beta` currently point to. Tells you which prerelease line is active.

npm view next dist-tags

npm view typescript dist-tags --json

pnpm view react dist-tags

Emit the audit report as machine-readable JSON for CI gates and dashboards. Pipe through jq to count only high/critical findings.

⚠ Common pitfall: Gate on the count, not the exit code: `npm audit --json | jq '.metadata.vulnerabilities.critical'`. The raw exit code is non-zero on any finding, which is too noisy for a useful gate.

npm audit --json

npm audit --json | jq '.metadata.vulnerabilities'

pnpm audit --json

Verify that installed packages’ registry signatures and provenance attestations are valid. Detects tampering between the registry and your machine.

⚠ Common pitfall: Run this in CI after `npm ci` to catch a compromised mirror or man-in-the-middle. Only works against registries that publish signatures (npmjs.org does).

npm audit signatures

# CI:
npm ci && npm audit signatures

Run a battery of environment health checks: registry reachability, Node/npm versions, cache integrity, git presence, and permissions on key folders.

⚠ Common pitfall: The fastest first move when installs misbehave on a new machine — it surfaces a wrong registry, a stale cache, or a permissions problem in one shot.

npm doctor

npm doctor --no-color

Check that the configured registry is reachable and measure round-trip latency. A one-line network sanity check before blaming your install.

npm ping

npm ping --registry=https://registry.npmmirror.com

Two branches added different deps → lock-file conflict. Do NOT hand-edit. Delete the lock file, re-run install, commit the regenerated file.

⚠ Common pitfall: Modern alternative: `git checkout --theirs` (or ours) on the lock file then `npm install` (or yarn/pnpm) — the package manager re-reconciles. Always re-run install before committing.

rm package-lock.json && npm install

git checkout --theirs pnpm-lock.yaml && pnpm install

Two of your deps want different versions of the same peer (often react). npm 7+ errors; yarn warns; pnpm errors loudly.

⚠ Common pitfall: Three escape hatches in order of preference: (1) upgrade the lagging dep, (2) use `overrides` (npm) / `resolutions` (yarn) / `pnpm.overrides` to force a single version, (3) `--legacy-peer-deps` as last resort.

npm pkg set overrides.react="18.2.0"

"resolutions": { "react": "18.2.0" }

pnpm i --legacy-peer-deps

Your code imports a package that is NOT in package.json but works because npm/yarn hoist it from a transitive dep. Breaks when the transitive dep changes.

⚠ Common pitfall: pnpm prevents this by default — its non-flat node_modules only exposes declared deps. Run `pnpm install` on a suspected project to surface every phantom dep at once.

# Add the missing dep:
npm install <pkg>

pnpm install  # exposes phantoms

# Detect with:
npx depcheck

Some legacy tools (next, eslint plugins) assume a flat node_modules. pnpm offers `shamefully-hoist=true` in .npmrc to mimic npm layout for compatibility.

⚠ Common pitfall: Turning hoist on hides phantom-dep bugs again — defeats half of pnpm. Prefer `public-hoist-pattern[]` to hoist only specific packages (eslint-*, prettier-*) instead.

# .npmrc
shamefully-hoist=true

# Better:
public-hoist-pattern[]=*eslint*
public-hoist-pattern[]=*prettier*

Yarn v1 (classic) and v2+ (berry) are different products. Berry defaults to Plug-n-Play (no node_modules), removed `yarn global`, uses .yarn/cache committed to repo.

⚠ Common pitfall: Switching takes real work — most projects either stay on classic or jump to pnpm. To check version: `yarn --version`. To switch to berry: `yarn set version stable`.

yarn --version

yarn set version stable  # → berry

yarn set version classic  # → v1

Local dev: `install` so you can add/remove deps. CI/CD and deploys: `npm ci` for deterministic, fast, fresh installs that fail if the lock file is out of sync.

⚠ Common pitfall: npm ci is 2-3x faster than install in CI because it skips dep resolution. Yarn/pnpm equivalents: `yarn install --frozen-lockfile` / `pnpm install --frozen-lockfile`.

# Local:
npm install lodash

# CI:
npm ci

pnpm install --frozen-lockfile

Global install fails with permission errors because /usr/local/lib is owned by root. DO NOT use `sudo npm install -g` — fix the prefix instead.

⚠ Common pitfall: `sudo` makes all your globally installed binaries owned by root, which causes cascading permission issues. Use a Node version manager (nvm, fnm, volta) — they put everything in your home dir.

npm config set prefix ~/.npm-global

export PATH=~/.npm-global/bin:$PATH

# Even better:
curl -fsSL https://fnm.vercel.app/install | bash

pnpm reports a peer-dep mismatch as an ERROR (npm only warns). Either fix the version, add to `pnpm.overrides`, or relax with `strict-peer-dependencies=false`.

⚠ Common pitfall: Relaxing peers globally hides real bugs. Per-package overrides are safer: `"pnpm": { "peerDependencyRules": { "ignoreMissing": ["@types/*"] } }`.

# .npmrc
strict-peer-dependencies=false

"pnpm": { "overrides": { "react": "18.2.0" } }

npm reads .npmrc from project root, then $HOME, then npm prefix, then npm builtin — first match wins. Project-level config is law.

⚠ Common pitfall: A stale `.npmrc` in a parent directory can leak into a child project (npm walks UP looking for them). Run `npm config list` to see exactly which files contributed.

# Project .npmrc beats user .npmrc:
echo "registry=https://npm.example.com" > .npmrc

npm config list  # see all sources

Apps: COMMIT the lock file (everyone gets the same versions). Libraries: usually DO NOT commit (consumers should pick their own). The classic source of "works for me" bugs.

⚠ Common pitfall: If you write a library AND ship a CLI from the same repo, commit the lock — your CLI users get the tested versions. Most ESLint-plugin / framework starter authors get this wrong.

# App: commit
git add package-lock.json

# Pure library: ignore
echo "package-lock.json" >> .gitignore

package.json `"engines": { "node": ">=18" }` is informational by default — npm/yarn warn but still install. Enforce with `engine-strict=true` in .npmrc.

⚠ Common pitfall: pnpm enforces engines by default — installs fail on wrong Node version. This catches real "works on dev, breaks in prod" bugs.

# .npmrc
engine-strict=true

"engines": { "node": ">=20", "pnpm": ">=9" }

To force a single version of a deeply-nested transitive dep, npm uses `"overrides"`, yarn uses `"resolutions"`, pnpm uses `"pnpm.overrides"`. Same goal, three different package.json keys.

⚠ Common pitfall: Overrides are a sledgehammer — you are overruling what a dependency declared it needs. Document WHY (usually a security patch) and revisit after the upstream fix lands.

"overrides": { "semver": "7.5.4" }

"resolutions": { "**/semver": "7.5.4" }

"pnpm": { "overrides": { "semver@<7.5.2": "7.5.4" } }

Installing globals with sudo makes every global binary owned by root and breaks future non-sudo installs with EACCES. The fix is a Node version manager, not more sudo.

⚠ Common pitfall: Already stuck? `sudo chown -R $(whoami) $(npm config get prefix)` reclaims ownership, then switch to fnm/nvm/volta so it never happens again.

# Wrong:
sudo npm install -g pnpm

# Right:
curl -fsSL https://fnm.vercel.app/install | bash

sudo chown -R $(whoami) $(npm config get prefix)

Running npm in a yarn project (or vice versa) generates a second lock file. Two lock files mean two sources of truth and silent version drift between developers and CI.

⚠ Common pitfall: Pin one tool with the `packageManager` field and enable Corepack so the wrong command refuses to run. Gitignore the foreign lock files as a backstop.

"packageManager": "pnpm@9.1.0"

# .gitignore
yarn.lock
package-lock.json

npx only-allow pnpm

Add `"preinstall": "npx only-allow pnpm"` so anyone running `npm install` or `yarn` in a pnpm repo gets blocked with a clear message before a stray lock file appears.

⚠ Common pitfall: preinstall runs before deps exist, so only-allow ships standalone via npx. Pair with Corepack: only-allow blocks the wrong tool, Corepack pins the right version.

"preinstall": "npx only-allow pnpm"

"preinstall": "npx only-allow yarn"

A malicious dependency can run arbitrary code via its `postinstall` hook the moment you install it. This is the most common npm supply-chain attack vector.

⚠ Common pitfall: Default to `ignore-scripts=true` in .npmrc, then allow-list trusted packages. pnpm 9+ asks for confirmation before running build scripts of newly-added deps.

# .npmrc
ignore-scripts=true

npm install --ignore-scripts

# pnpm 9+ approve list:
onlyBuiltDependencies

`^1.2.3` allows any 1.x.y (minors + patches); `~1.2.3` allows only 1.2.y (patches). For 0.x both behave differently: `^0.2.3` is locked to 0.2.y because 0.x majors are breaking.

⚠ Common pitfall: The 0.x rule trips people up constantly: under semver, every 0.x bump can break. So `^0.3.0` will NOT auto-update to 0.4.0 — it behaves like `~0.3.0`.

"react": "^18.2.0"  // 18.x.x

"react": "~18.2.0"  // 18.2.x

"some-lib": "^0.3.0"  // 0.3.x only

Inside an npm/yarn/pnpm script, `node_modules/.bin` is prepended to PATH automatically. That is why `"build": "vite build"` works without `npx` or `./node_modules/.bin/`.

⚠ Common pitfall: This magic ONLY applies inside scripts. In a plain terminal you still need `npx vite` or `pnpm exec vite`. That gap is why "works in package.json, fails in my shell" happens.

"build": "vite build"  // no npx needed

# in shell:
npx vite build

pnpm exec vite build

What ends up in the published tarball is controlled by the `"files"` allow-list in package.json OR a `.npmignore` deny-list. If `"files"` exists it wins; otherwise `.npmignore` (falling back to `.gitignore`) applies.

⚠ Common pitfall: Always verify with `npm pack --dry-run` before publishing. The recurring leak is a `.env`, a `src/` you meant to exclude, or test fixtures bloating the package. `"files"` allow-listing is safer than denying.

"files": ["dist", "README.md"]

npm pack --dry-run

tar -tzf my-pkg-1.0.0.tgz

When NODE_ENV is `production`, a bare `npm install` skips devDependencies. This bites in Docker builds that need build tools (typescript, vite) that live in devDependencies.

⚠ Common pitfall: Either move build tools to dependencies, or run `npm install --include=dev` in the build stage and `npm ci --omit=dev` only in the final runtime stage of a multi-stage Dockerfile.

npm install --include=dev

# Multi-stage Docker:
RUN npm ci
RUN npm run build
# then runtime:
RUN npm ci --omit=dev