vdiff

A breaking-change diff API for npm packages. Given a package and two versions, it returns a structured, machine-readable list of what actually broke: removed exports, changed function signatures, and removed or changed class and interface members. Each entry includes the before and after signatures plus a short migration note.

Live at https://vdiff-api.onrender.com. Most easily consumed through the MCP server, vdiff-mcp:

claude mcp add vdiff -- npx -y vdiff-mcp

Or call the REST API directly:

curl "https://vdiff-api.onrender.com/v1/diff?ecosystem=npm&package=zod&from=3.24.0&to=4.0.0"

Why this exists

LLMs learn a package's API surface during training, then the package moves on. When a coding agent writes code against zod or express, it writes for the version it remembers, which is often not the version in your lockfile. The result is confident code that calls functions that were renamed or removed two majors ago.

Existing tools only solve part of this. Version lookup tools tell the agent what the current version is. Documentation tools tell it what the docs say today. Neither answers the question the agent actually has mid-edit: "what changed between the version I know and the version installed here?"

vdiff answers exactly that. Diffs are computed from the package's own type declarations rather than changelogs, so the output reflects the real exported surface, and every response carries a confidence score so the consumer knows how much to trust it.

Endpoint reference: docs/api.md.

How it works

1. Resolve. Fetch package metadata, versions and dist-tags from the npm registry.
2. Extract. For each of the two versions, download the tarball, keep only the .d.ts files, and build a table of public exports (functions, classes, members, normalized call signatures) using the TypeScript compiler API. Bundled declarations are preferred; packages that ship none fall back to the matching DefinitelyTyped @types/* package, version-matched by major.minor.
3. Compare. Diff the two export tables into typed change entries (export_removed, signature_changed, member_removed and so on), each with before/after signatures and a migration note.
4. Cache and meter. Results are stored in Postgres keyed on (package, from, to), so each version pair is computed once, ever. Every request is logged with cache-hit status and user agent.
5. Guard. Per-IP rate limits, a cap on simultaneous diff computations, size limits on tarballs and extracted declarations, and fetch timeouts keep the service safe to expose publicly.

Diffs are type-level: a runtime behavior change that leaves the types untouched is invisible. Responses using bundled types carry confidence 0.9; responses using community-maintained @types/* declarations carry 0.8.

API overview

See docs/api.md for parameters, response shapes, change types, error codes and rate limits.

Stack

... View full README on GitHub