NPM

When to Use

• Installing, updating, or removing npm packages
• Pinning dependency versions in package.json
• Managing transitive dependency overrides

Procedure

1. Pin Exact Versions

Always pin exact dependency versions in package.json (no ^ or ~ ranges). This makes any fresh npm install deterministic regardless of what’s been published upstream. The lockfile becomes a disposable artifact, not a lifeline.

To remove a package: npm uninstall <pkg>

To upgrade: explicitly set the new version in package.json.

2. Overrides for Transitive Deps

Pinning exact versions only controls direct dependencies. Transitive deps (like zod pulled in by @astrojs/sitemap) can still float. Use the npm overrides field to pin critical transitive dependencies.

This is especially important when a transitive dep has a major version range (e.g., "^3.25 || ^4") — any npm install can resolve it to the newer major. The overrides field is the only way to prevent this permanently.

3. Scope Names Drop Hyphens

When a GitHub username contains hyphens (e.g., jason-tan-swe), the corresponding npm scope drops the hyphens: @jasontanswe/... (not @jason-tan-swe/...). Always verify the npm package name at npmjs.com — the GitHub repo name and npm scope can differ.

Gotchas

• Unpinned versions can cause different behavior across npm install runs
• Transitive deps with major version ranges are especially dangerous without overrides
• npm scope names may differ from GitHub usernames (hyphens dropped)