Breaking Change Exposure: Know What Will Break Before You Upgrade

The Element of Surprise

Every developer has experienced the optimistic version bump that turned into a two-day debugging session. You update a dependency, run the tests, and discover that three APIs were renamed, a configuration option was removed, and a peer dependency now conflicts with another package.

The frustration is not the work — it is the surprise. If you had known upfront what would break, you could have planned for it, scoped it, and scheduled it.

That is exactly what Vibgrate's Breaking Change Exposure scanner does.

What It Detects

The Breaking Change Exposure scanner flags packages and patterns known to cause upgrade pain:

Deprecated Packages

Packages that the ecosystem has moved on from. These are not just old — they are packages where the maintainers have explicitly said "stop using this":

request — deprecated in favour of node-fetch, undici, or native fetch
node-sass — replaced by dart-sass / sass
tslint — replaced by ESLint with @typescript-eslint
moment — effectively superseded by date-fns, dayjs, or Temporal

Legacy Node API Polyfills

Packages that polyfill APIs that are now native in modern Node.js (18+):

node-fetch — globalThis.fetch is built-in since Node 18
abort-controller — native since Node 16
querystring — native URLSearchParams is preferred

If your target runtime supports these APIs natively, the polyfill is dead weight — and sometimes a source of subtle bugs when the polyfill behavior diverges from the native implementation.

Peer Dependency Conflicts

Cases where upgrading one package would create a conflict with another package's peer dependency requirements. These conflicts are the leading cause of "upgrade cascade" — where bumping one package forces you to bump five others.

Exposure Score

The scanner produces an exposure score (0–100) that quantifies your overall breaking change risk. A score of 0 means no detected exposure. A score of 100 means widespread use of deprecated, legacy, and conflicting packages.

How to Use the Information

The Breaking Change Exposure output is designed for upgrade planning:

Before starting an upgrade sprint: Run vibgrate scan . and check the breaking change findings. They tell you which upgrades will be straightforward version bumps and which will require code changes.
When estimating upgrade tickets: Each finding includes detail about what the replacement is and how widespread the usage is. This turns vague "upgrade X" tickets into scoped "replace node-sass with sass in 12 files" tasks.
When evaluating new dependencies: Before adding a new package, check whether it depends on deprecated or soon-to-be-deprecated packages. A dependency with a clean exposure profile is a safer bet.

Configuration

The scanner is enabled by default. To disable it:

// vibgrate.config.ts
scanners: {
  breakingChangeExposure: { enabled: false },
}

But we recommend keeping it on — the information is too valuable for upgrade planning to skip.

The Vibgrate Drift Intelligence Engine surfaced breaking change exposure because upgrade drift is not just about how far behind you are — it is about how hard it will be to catch up. A drift score of 50 with low exposure is a very different situation than a drift score of 50 with high exposure.

Know before you upgrade. Sign up at dash.vibgrate.com to scan your codebase for breaking change exposure and scope your upgrade work with confidence.