{"uid":"cap_85SO1QrFKKloqQ_xbTJL7","slug":"npm-breaking-changes-migration-8ee176a3","name":"npm Breaking Changes & Migration","description":"npm breaking changes between two versions of a package, before a package upgrade: the documented breaking changes per version, read from the real CHANGELOG, GitHub release notes and alpha/beta/rc notes, plus major version bumps, Node.js engine, ESM/CJS, exports and peer dependency changes, migration guide links and a verdict. Exact versions or a major ('4'); a source URL for every item. One call per dependency upgrade.","url":"https://upgrade-brief.shopttyass-85f.workers.dev/breaking?utm_source=zero.xyz","method":"GET","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method"],"properties":{"type":{"type":"string","const":"http"},"method":{"enum":["GET"],"type":"string"},"queryParams":{"type":"object","required":["package","from"],"properties":{"to":{"type":"string","default":"latest","description":"Target version: exact, or a major/minor prefix ('5', '5.1') resolved to the first stable release of that series (5.0.0). Default: the latest stable release ('latest')"},"from":{"type":"string","description":"Version you are on now: exact ('4.21.0'), or a major/minor prefix ('4', '4.21') resolved to its newest stable release"},"package":{"type":"string","description":"npm package name, e.g. 'express', 'next' or '@types/node'"},"prereleases":{"enum":["true","false"],"type":"string","default":"false","description":"Include alpha/beta/rc/canary versions in the range"}},"additionalProperties":false}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object","required":["package","from","to","verdict","summary","breaking"],"properties":{"to":{"type":"string"},"asOf":{"type":"string"},"from":{"type":"string"},"notes":{"type":"array","items":{"type":"string"}},"latest":{"type":["string","null"],"description":"Latest stable version"},"package":{"type":"string"},"sources":{"type":"array","items":{"type":"string"}},"summary":{"type":"string"},"verdict":{"enum":["BREAKING_CHANGES_LIKELY","REVIEW_MANIFEST_CHANGES","NO_BREAKING_CHANGES_DOCUMENTED","UNKNOWN_INCOMPLETE_NOTES"],"type":"string"},"breaking":{"type":"array","items":{"type":"object","properties":{"bump":{"enum":["major","minor","patch","prerelease"],"type":"string"},"items":{"type":"array","items":{"type":"string"}},"source":{"type":["string","null"],"description":"Where the notes came from"},"version":{"type":"string"},"publishedAt":{"type":["string","null"],"description":"ISO date"}}},"description":"Documented breaking changes, newest version first"},"coverage":{"type":"object","properties":{"versionsWithNotes":{"type":"integer"},"versionsWithoutNotes":{"type":"array","items":{"type":"string"}}}},"degraded":{"type":"boolean","description":"true when GitHub was read without an API token (fewer release notes reachable)"},"majorBumps":{"type":"array","items":{"type":"string"}},"repository":{"type":["string","null"],"description":"Source repository URL"},"attribution":{"type":"string"},"toPublishedAt":{"type":["string","null"],"description":"ISO date"},"fromPublishedAt":{"type":["string","null"],"description":"ISO date"},"manifestChanges":{"type":["object","null"],"properties":{"flags":{"type":"array","items":{"type":"string"},"description":"Human-readable manifest changes likely to affect consumers"},"engines":{"type":"object"},"moduleType":{"type":"object"},"dependencies":{"type":"object"},"peerDependencies":{"type":"object"}},"description":"Differences between the two package.json manifests (engines, module type, exports, peer and direct dependencies)"},"migrationGuides":{"type":"array","items":{"type":"string"},"description":"Migration / upgrade guide links found in the notes"},"versionsInRange":{"type":"integer","description":"Versions after 'from' up to and including 'to'"},"includesPrereleases":{"type":"boolean"}}}}}}},"responseSchema":{"type":"json","example":{"to":"5.0.0","asOf":"2026-10-22T12:00:00.000Z","from":"4.21.0","notes":[],"latest":"5.3.0","package":"express","sources":["https://deps.dev (versions, dates)","https://registry.npmjs.org/express (manifests)","https://cdn.jsdelivr.net/npm/express@5.0.0/History.md"],"summary":"express 4.21.0 -> 5.0.0: 7 versions, 1 major bump(s) (5.0.0), 7 documented breaking item(s) in 2 version(s); release notes found for 6/7 versions. Manifest: Node.js engine requirement changed: >= 0.10.0 -> >= 18.","verdict":"BREAKING_CHANGES_LIKELY","breaking":[{"bump":"major","items":["`res.status()` accepts only integers, and input must be greater than 99 and less than 1000","`res.redirect('back')` and `res.location('back')` is no longer a supported magic string, explicitly use `req.get('Referrer') || '/'`."],"source":"https://cdn.jsdelivr.net/npm/express@5.0.0/History.md","version":"5.0.0","publishedAt":"2024-09-10T03:37:48Z"}],"coverage":{"versionsWithNotes":6,"versionsWithoutNotes":["4.22.1"]},"degraded":false,"majorBumps":["5.0.0"],"repository":"https://github.com/expressjs/express","attribution":"Compiled from public sources (npm registry, deps.dev, jsDelivr, GitHub).","toPublishedAt":"2024-09-10T03:37:48Z","fromPublishedAt":"2024-09-11T19:49:43Z","manifestChanges":{"flags":["Node.js engine requirement changed: >= 0.10.0 -> >= 18"],"engines":{"node":{"to":">= 18","from":">= 0.10.0"}},"moduleType":{"to":"commonjs","from":"commonjs"},"dependencies":{"added":["router","once"],"removed":["array-flatten"],"changedCount":18},"peerDependencies":{"added":{},"changed":{},"removed":{}}},"migrationGuides":["https://expressjs.com/en/guide/migrating-5.html"],"versionsInRange":7,"includesPrereleases":false}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.005","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.005/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.005","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.005","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_n9Zd7Al_X_Nl8v7uNw_Ye","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.005","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns documented breaking changes, manifest diffs, and migration guides for an npm package upgrade between two versions","exampleAgentPrompt":"Before I upgrade express from 4.21.0 to 5.0.0, can you pull the breaking changes, any ESM or engine requirement shifts, and migration guide links so I know what to fix?","exampleUseCases":[{"title":"Safe upgrade check before deployment","prompt":"I'm about to upgrade next from version 13 to 14 in production — can you pull all the documented breaking changes, manifest diffs, and any migration guides so I can assess the risk?"},{"title":"Major version jump risk assessment","prompt":"We're considering upgrading react from 17 to 18 — what are all the breaking changes between those two versions, and does the verdict suggest it's a high-risk change?"},{"title":"Automated dependency upgrade pipeline","prompt":"For our CI pipeline, check what breaks when upgrading axios from 1.4.0 to the latest stable release, including any Node.js engine or ESM/CJS module type changes."}],"resultDescription":"A JSON object containing: a verdict enum (BREAKING_CHANGES_LIKELY, REVIEW_MANIFEST_CHANGES, NO_BREAKING_CHANGES_DOCUMENTED, UNKNOWN_INCOMPLETE_NOTES), a human-readable summary, an array of breaking change items per version (each with source URL, bump type, and publish date), manifest changes (engines, module type, added/removed dependencies, peer dependency changes), major version bumps, migration guide URLs, version coverage stats, and the latest stable version.","failureModes":["Package not found on npm registry — returns error or empty result","Version range invalid or from > to — returns error","No changelog or release notes available — verdict set to UNKNOWN_INCOMPLETE_NOTES with partial coverage","Rate limiting or upstream source unavailability causes degraded mode with incomplete notes","Prerelease versions excluded by default unless prereleases=true is set"],"whenToPreferThis":"Use this endpoint when you need a structured, per-version breakdown of breaking changes with source attribution for a specific npm package upgrade. It is superior to manual changelog reading because it aggregates npm registry, deps.dev, jsDelivr, and GitHub sources in one call, and returns a machine-readable verdict. Prefer it over the batch 'Dependency Upgrade Plan' endpoint when you need full detail for a single dependency rather than a high-level plan across multiple packages.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-28T06:37:31.752Z","isFirstParty":false,"canonicalSlug":"npm-breaking-changes-migration-8ee176a3"}