How to track breaking changes in your npm dependencies

npm outdated lists every dependency with a newer version. The two columns that matter: “wanted is the maximum version of the package that satisfies the semver range specified in package.json”, and “latest is the version of the package tagged as latest in the registry.”

Package       Current  Wanted  Latest  Location                   Depended by
some-parser     1.8.2   1.9.0   2.1.0  node_modules/some-parser   my-app
some-logger     3.2.0   3.2.4   3.2.4  node_modules/some-logger   my-app

• Current → Wanted is what npm update would install within your range. If the package follows Semantic Versioning, that's features and fixes only.
• Wanted → Latest across a major number (1.9.0 → 2.1.0 above) is where the breaking changes are. Semantic Versioning reserves the major version for “incompatible API changes”.
• latest is a tag the maintainer moves; npm notes it “may or may not be the maximum version of the package, or the most-recently published version”.

When you npm install a package, npm saves it with the save-prefix, which defaults to ^. Here's what the common ranges allow, from the node-semver docs:

node-semver writes the upper bounds as <2.0.0-0 and so on, so prereleases of the next major are excluded too. Commit package-lock.json; npm says it's “intended to be committed into source repositories”, so a range never changes what CI installs without a pull request. More on version numbers in Semantic Versioning and changelogs.

Dependency bots are the best early warning, if majors arrive on their own. Renovate already does this: separateMajorMinor defaults to true, creating “a separate branch/PR if both minor and major version updates exist”, and fetchChangeLogs defaults to fetching changelogs and release notes into the pull request. To make every major wait for an explicit yes on its Dependency Dashboard:

{
  "packageRules": [
    {
      "matchUpdateTypes": ["major"],
      "dependencyDashboardApproval": true
    }
  ]
}

With Dependabot, group minor and patch updates so each major stands alone as its own pull request:

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    groups:
      non-major:
        update-types: ["minor", "patch"]

Dependabot can also ignore majors with update-types: ["version-update:semver-major"], but then nothing tells you they exist. Separate pull requests are a better default than silence.

• Watch releases. On a dependency's GitHub repository, choose Watch → Custom and pick releases. You'll hear about new versions without the issue and pull request noise.
• Read deprecation warnings. npm deprecate makes npm show “a deprecation warning to all who attempt to install it”; a deprecated version or package is often the first sign of a removal.
• Trace runtime deprecations. Run your tests with node --trace-deprecation to print a stack trace for each deprecation warning, so you know which code to change.
• Notice editor hints. APIs marked @deprecated in JSDoc or TypeScript are “typically displayed in a strike-through style” in editors like VS Code.

Going from 1.8.2 to 2.1.0 means reading 1.9.0, 2.0.0, 2.0.1 and 2.1.0, because a deprecation in 1.9 can become a removal in 2.0. Find the changelog with npm view some-package repository.url, then look for, in order: breaking changes, Removed, Deprecated, and any minimum Node.js or peer-dependency change.

Large projects publish a migration guide per major, such as Vite's. For libraries that host their changelog on LogPulse, an upgrade page lists every breaking change and migration step between any two versions, like this example from 1.4.0 to 2.0.0. For anything else, paste the releases page into the free converter to get the breaking changes of each version in one list.

Coding agents are good at mechanical migrations, if they know what changed. Give the agent the dependency's breaking changes and migration steps for the exact version range, not a vague “upgrade to latest”. A structured changelog makes that possible; changelogs for AI coding agents explains the format, and maintainers can see the other side in how to document breaking changes.