sentry-sdk-upgrade

An AI-guided migration workflow for upgrading the Sentry JavaScript SDK across major versions. It is meant for moving from v7 to v8, v8 to v9, or any major jump, fixing deprecated Sentry APIs, and resolving breaking changes or errors that appear after a version bump. The workflow proceeds through four phases: Detect, Recommend, Guide, and Cross-Link.

Detection reads package.json to find all @sentry/* packages and the current major version, then identifies the framework from dependency indicators, mapping signals such as next, nuxt, @sveltejs/kit, @remix-run/node, react, @angular/core, vue, express, @nestjs/core, and others to their Sentry packages (for example @sentry/nextjs, @sentry/node, @sentry/react). It locates Sentry config and instrumentation files and scans for deprecated patterns that signal which migration steps are needed, including v7 markers like @sentry/hub, @sentry/tracing, BrowserTracing, startTransaction, and configureScope, and v8 markers like @sentry/utils, getCurrentHub, enableTracing, and autoSessionTracking. The Recommend phase computes the migration path, handling single hops and multi-hop upgrades (applying v7-to-v8 changes first, then v8-to-v9, while updating package versions once to the final target), and presents a breaking-changes summary categorized as auto-fixable (import and method renames, config option swaps), AI-assisted (hub removal, transactions-to-spans migration, complex config restructuring), and manual review (removed APIs, behavioral changes).

The Guide phase steps through each file with Sentry imports, applying auto-fixable changes directly, proposing AI-assisted edits with explanation, and flagging uncertain changes for confirmation, working in order through package imports, API renames, config changes, complex pattern migration, and finally updating package.json with all packages on the same major version using the detected package manager (npm, yarn, or pnpm). It then verifies the build with tsc --noEmit and the project build, applies framework-specific steps, and in Cross-Link confirms all packages match, imports resolve, types compile, the build succeeds, and tests pass, optionally adding a temporary thrown error to confirm Sentry works and mentioning new features in the target version.