sentry-sdk-upgrade

$27

cat package.json | grep -E '"@sentry/' | head -20

Extract:

• All @sentry/* packages and their current versions

• The current major version (e.g., 7.x, 8.x, 9.x)

1.2 Detect Framework

Check package.json dependencies for framework indicators:

Dependency

Framework

Sentry Package

next

Next.js

@sentry/nextjs

nuxt or @nuxt/kit

Nuxt

@sentry/nuxt

@sveltejs/kit

SvelteKit

@sentry/sveltekit

@remix-run/node

Remix

@sentry/remix

react (no Next/Remix)

React SPA

@sentry/react

@angular/core

Angular

@sentry/angular

vue (no Nuxt)

Vue

@sentry/vue

express

Express

@sentry/node

@nestjs/core

NestJS

@sentry/nestjs

@solidjs/start

SolidStart

@sentry/solidstart

astro

Astro

@sentry/astro

bun types or runtime

Bun

@sentry/bun

@cloudflare/workers-types

Cloudflare

@sentry/cloudflare

None of above (Node.js)

Node.js

@sentry/node

1.3 Find Sentry Config Files

grep -rn "from '@sentry/\|require('@sentry/" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" --include="*.mjs" --include="*.cjs" -l

find . -name "sentry.*" -o -name "*.sentry.*" -o -name "instrumentation.*" | grep -v node_modules | grep -v .next | grep -v .nuxt

1.4 Detect Deprecated Patterns

Scan for patterns that indicate which migration steps are needed:

# v7 patterns (need v7→v8 migration)

grep -rn "from '@sentry/hub'\|from '@sentry/tracing'\|from '@sentry/integrations'\|from '@sentry/serverless'\|from '@sentry/replay'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -l

grep -rn "new BrowserTracing\|new Replay\|startTransaction\|configureScope\|Handlers\.requestHandler\|Handlers\.errorHandler" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -l

# v8 patterns (need v8→v9 migration)

grep -rn "from '@sentry/utils'\|from '@sentry/types'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -l

grep -rn "getCurrentHub\|enableTracing\|captureUserFeedback\|@WithSentry\|autoSessionTracking" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -l

1.5 Determine Target Version

If the user didn't specify a target version, recommend the latest major version (v9 as of this writing). If the user has already bumped package versions but has broken code, detect the target from package.json.

Phase 2: Recommend

Present a migration summary based on detected state.

2.1 Calculate Migration Path

• Single hop: e.g., v8 to v9

• Multi-hop: e.g., v7 to v9 (apply v7→v8 changes first, then v8→v9)

For multi-hop migrations, apply code changes incrementally but update package versions once to the final target.

2.2 Present Breaking Changes Summary

Load the appropriate version-specific reference:

• v7→v8: references/v7-to-v8.md

• v8→v9: references/v8-to-v9.md

• v9→v10: references/v9-to-v10.md

Present a concrete summary of changes needed, categorized by complexity:

Auto-fixable (apply directly):

• Package import renames (e.g., @sentry/utils to @sentry/core)

• Simple method renames (e.g., @WithSentry to @SentryExceptionCaptured)

• Config option swaps (e.g., enableTracing to tracesSampleRate)

AI-assisted (explain and propose):

• Hub removal with variable storage patterns

• Performance API migration (transactions to spans)

• Complex config restructuring (Vue tracing options, Next.js config merging)

• Sampler transactionContext flattening

Manual review (flag for user):

• Removed APIs with no equivalent

• Behavioral changes (sampling, source maps defaults)

• Custom transport modifications

2.3 Confirm Scope

Ask the user:

• Confirm the migration path (e.g., "v8 to v9")

• Confirm whether to proceed with all changes or specific categories

• Note: npx @sentry/wizard -i upgrade exists as a CLI alternative for v8→v9 but may not handle all patterns

Phase 3: Guide

Step through changes file by file.

3.1 Process Each File with Sentry Imports

For each file identified in Phase 1.3:

• Read the file to understand current Sentry usage

• Apply auto-fixable changes directly:

• Package import renames

• Method/function renames

• Simple config option swaps

• For AI-assisted changes, explain what needs to change and why, then propose the specific edit

• For uncertain changes, show the code and ask the user to confirm

3.2 Apply Changes by Category

Work through changes in this order:

#### Step 1: Package Import Updates

Replace removed/renamed package imports. Reference the version-specific migration file for the complete mapping.

#### Step 2: API Renames

Apply mechanical method and function renames.

#### Step 3: Config Changes

Update Sentry.init() options and build configuration.

#### Step 4: Complex Pattern Migration

Handle patterns requiring understanding of context:

• Hub usage stored in variables

• Transaction-based performance code

• Custom integration classes

• Framework-specific wrappers

#### Step 5: Update package.json Versions

Update all @sentry/* packages to the target version. All packages must be on the same major version.

# Detect package manager

if [ -f "yarn.lock" ]; then

  echo "yarn"

elif [ -f "pnpm-lock.yaml" ]; then

  echo "pnpm"

else

  echo "npm"

fi

Install updated dependencies using the detected package manager.

#### Step 6: Verify Build

# Check for type errors

npx tsc --noEmit 2>&1 | head -50

# Run build

npm run build 2>&1 | tail -20

Fix any remaining type errors or build failures.

3.3 Framework-Specific Steps

Consult references/upgrade-patterns.md for framework-specific config file locations and validation steps.

Next.js: Check instrumentation.ts, next.config.ts wrapper, both client and server configs.

Nuxt: Check Nuxt module config and both plugin files.

SvelteKit: Check hooks files and Vite config.

Express/Node: Verify early initialization order.

NestJS: Check for decorator and filter renames.

Phase 4: Cross-Link

4.1 Verify

• All @sentry/* packages on same version

• No import errors from removed packages

• TypeScript compilation passes

• Build succeeds

• Tests pass (if they exist)

Suggest adding a test error:

// Add temporarily to verify Sentry is working after upgrade

setTimeout(() => {

  throw new Error('Sentry upgrade verification - safe to delete');

}, 3000);

4.2 New Features in Target Version

Mention features available in the new version that the user might want to enable:

v8 new features: OpenTelemetry-based Node tracing, automatic database/HTTP instrumentation, functional integrations, new span APIs

v9 new features: Structured logging (Sentry.logger.*), improved source maps handling, simplified configuration

4.3 Related Resources

• Official Migration Guide (v7→v8)

• Official Migration Guide (v8→v9)

• Sentry JavaScript SDK Changelog

If the user has other Sentry SDKs (Python, Ruby, Go, etc.) that also need upgrading, note that this skill covers JavaScript SDK only.