JavaScript package upgrades

npm, pnpm & Yarn Upgrades

When to Use

Use when upgrading Node.js, frontend, or full-stack JavaScript/TypeScript packages managed by npm, pnpm, yarn (v1 or Berry v3/v4), or bun.

Package Manager Mechanics & Discipline

1. Respect Corepack & Lockfile Format

• Check root package.json "packageManager" (e.g., "pnpm@9.12.0", "yarn@4.5.0") and .npmrc / .yarnrc.yml.
• Use only the repository's active package manager:
  • npm: npm install <pkg>@<version> updates package.json and package-lock.json. Use npm dedupe when transitive trees fragment after an update. Never use --legacy-peer-deps or --force without proving the peer mismatch is benign at runtime.
  • pnpm: Strict node_modules layout prevents phantom dependencies (importing undeclared transitive packages). Use pnpm up <pkg>@<version> (or -r across workspaces). If an upgraded package fails because it relied on hoisted undeclared dependencies, fix the manifest or use .pnpmfile.cjs / packageExtensions rather than shamefully-hoist=true.
  • Yarn Berry (v2–v4): Inspect .yarnrc.yml (nodeLinker: pnp | pnpm | node-modules). With Plug'n'Play (pnp), undeclared peer dependencies throw YN0002 / ERR_PNPM_PEER_DEP_ISSUES; declare missing peers via packageExtensions in .yarnrc.yml and run yarn dedupe.

2. ESM / CJS Interop & exports Map Transitions

Many modern JS packages drop CommonJS (require()) in major upgrades (e.g., chalk, execa, nanoid, ora, file-type, unified, Rehype/Remark ecosystem):

• Inspect the target package's package.json for "type": "module" and "exports" conditions (import, require, types, default, node, browser).
• If the consuming project compiles to CommonJS ("module": "CommonJS" in tsconfig.json or no "type": "module"), upgrading to an ESM-only package will fail at runtime with ERR_REQUIRE_ESM unless:
  1. The project or build target is migrated to ESM ("type": "module", "moduleResolution": "NodeNext" | "Bundler"), or
  2. The package is bundled by Vite/esbuild/Webpack (ssr.noExternal / transpilePackages), or
  3. You stay on the maintained CJS-compatible major line (and document why).
• Never replace a static import with an untested await import() inside synchronous hot paths just to silence ERR_REQUIRE_ESM.

3. TypeScript & @types/* Alignment

• Check whether the upgraded package now bundles its own .d.ts declarations ("types" or "typings" in its package.json). If so, remove the obsolete @types/<pkg> devDependency so staleDefinitelyTyped definitions do not shadow the official types.
• Keep @types/node aligned with the project's actual target Node.js LTS major (engines.node, .nvmrc, Dockerfile), not a newer Node major that introduces globals unavailable in production.
• When upgrading typescript itself, check moduleResolution, stricter generic inference, verbatimModuleSyntax, and framework typecheckers (vue-tsc, @angular/compiler-cli, astro check, svelte-check).

4. Scoped Overrides, Resolutions & Lifecycle Scripts

• When pinning a transitive dependency:
  • npm: "overrides": { "parent-pkg": { "vulnerable-child": "1.2.3" } } (prefer scoped overrides over global overrides whenever possible).
  • pnpm: "pnpm": { "overrides": { "parent-pkg>vulnerable-child": "1.2.3" } }.
  • Yarn: "resolutions": { "parent-pkg/vulnerable-child": "1.2.3" }.
• Check .npmrc for ignore-scripts. When upgrading packages with lifecycle scripts (esbuild, sharp, playwright, cypress, lefthook, husky), verify postinstall binary resolution across local dev and CI.