Sentry Sdk Upgrade

All Skills > Workflow > SDK Upgrade

Sentry JavaScript SDK Upgrade

Upgrade the Sentry JavaScript SDK across major versions with AI-guided migration.

Invoke This Skill When

• User asks to "upgrade Sentry" or "migrate Sentry SDK"
• User mentions deprecated Sentry APIs or breaking changes after a version bump
• User wants to move from v7 to v8, v8 to v9, or any major version jump
• User encounters errors after updating @sentry/* package versions
• User asks about Sentry migration guides or changelogs

Phase 1: Detect

Identify the current Sentry SDK version, target version, and framework.

1.1 Read package.json

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:

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:

1. Read the file to understand current Sentry usage 2. Apply auto-fixable changes directly:

• Package import renames
• Method/function renames
• Simple config option swaps

3. For AI-assisted changes, explain what needs to change and why, then propose the specific edit 4. 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.

Sentry SDK Upgrade — General Patterns

Version-agnostic guidance for upgrading the Sentry JavaScript SDK across any major version.

Finding Sentry Code in a Project

Grep for All Sentry Imports

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

Find Sentry Config Files

# Common config file patterns
find . -name "sentry.*" -o -name "*.sentry.*" -o -name "instrumentation.*" | grep -v node_modules | grep -v .next

Check Current Sentry Version

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

# Actual installed version
ls node_modules/@sentry/*/package.json 2>/dev/null | head -5 | xargs -I{} sh -c 'echo "--- {} ---" && grep "\"version\"" {}'

Common Config File Locations by Framework

Package Manager Commands for Version Bumps

npm

# Upgrade all @sentry packages to latest
npm install @sentry/browser@latest @sentry/node@latest  # list all packages

# Or use npm-check-updates
npx npm-check-updates -f '@sentry/*' -u && npm install

yarn

# Upgrade all @sentry packages
yarn add @sentry/browser@latest @sentry/node@latest  # list all packages

# Or use yarn upgrade-interactive
yarn upgrade-interactive --latest

pnpm

# Upgrade all @sentry packages
pnpm update @sentry/browser@latest @sentry/node@latest  # list all packages

# Or update all Sentry packages at once
pnpm update '@sentry/*' --latest

Validation Steps After Upgrade

1. Install Dependencies

# Remove lockfile and node_modules for clean install (if needed)
rm -rf node_modules
npm install  # or yarn / pnpm install

2. Check for Type Errors

npx tsc --noEmit

3. Run Tests

npm test  # or yarn test / pnpm test

4. Build the Project

npm run build  # or yarn build / pnpm build

5. Verify Sentry Is Working

Add a test error to verify events reach Sentry:

// Temporarily add to any entry point
setTimeout(() => {
  throw new Error('Sentry SDK upgrade test - safe to delete');
}, 3000);

Check the Sentry dashboard for the test error, then remove it.

Framework-Specific Upgrade Considerations

Next.js

• Check both client and server Sentry configs
• Verify withSentryConfig wrapper in next.config.ts
• Ensure instrumentation.ts exists and loads Sentry server config
• Test both dev and production builds (next dev and next build)
• Check source maps upload in production build output

Nuxt

• Sentry module config in nuxt.config.ts may need updating
• Check both client and server plugin files
• Verify source maps configuration

SvelteKit

• Check sentryHandle() in hooks files
• Verify Vite plugin configuration
• Check sentryHandleError() setup

React (SPA)

• Verify browser tracing integration
• Check React Router integration version compatibility
• Test error boundary components

Express/Node

• Ensure Sentry is initialized before other imports (v8+)
• Verify error handler placement (setupExpressErrorHandler)
• Check custom middleware for Sentry scope usage

NestJS

• Verify @sentry/nestjs package (moved from @sentry/node in v9)
• Check decorators and filters for renames
• Remove deprecated SentryService and SentryTracingInterceptor

Multi-Hop Migrations

When upgrading across multiple major versions (e.g., v7 to v9):

1. Upgrade one major version at a time — apply v7→v8 changes, verify, then v8→v9 2. Update package versions once — bump to the final target version but apply code changes incrementally 3. Use the version-specific grep patterns to find code needing changes at each step 4. Test after each logical migration step — don't wait until all changes are made

Common Pitfalls

Sentry JavaScript SDK: v7 to v8 Migration Reference

This is the largest migration. v8 overhauled performance monitoring APIs, moved to OpenTelemetry, removed deprecated packages, and switched integrations from classes to functions.

Recommend upgrading to latest v7 first and removing deprecated v7 APIs before jumping to v8.

Version Support Changes

Package Removals

These packages were removed entirely in v8. Update imports accordingly.

@sentry/tracing Removal

Browser - Replace BrowserTracing class with browserTracingIntegration() function:

- import { BrowserTracing } from '@sentry/tracing';
  import * as Sentry from '@sentry/browser';

  Sentry.init({
    dsn: '__DSN__',
    tracesSampleRate: 1.0,
-   integrations: [new BrowserTracing()],
+   integrations: [Sentry.browserTracingIntegration()],
  });

Node - Simply remove the @sentry/tracing import:

  const Sentry = require('@sentry/node');
- require('@sentry/tracing');

  Sentry.init({
    dsn: '__DSN__',
    tracesSampleRate: 1.0,
  });

@sentry/integrations Removal

All integrations moved to @sentry/browser or @sentry/node and became functions:

@sentry/serverless Removal

- const Sentry = require('@sentry/serverless');
- Sentry.AWSLambda.init({ dsn: '__DSN__' });
+ const Sentry = require('@sentry/aws-serverless');
+ Sentry.init({ dsn: '__DSN__' });

- const Sentry = require('@sentry/serverless');
- Sentry.GCPFunction.init({ dsn: '__DSN__' });
+ const Sentry = require('@sentry/google-cloud-serverless');
+ Sentry.init({ dsn: '__DSN__' });

Integration API Overhaul

All integrations changed from classes to functions:

- integrations: [new Sentry.Replay()]
+ integrations: [Sentry.replayIntegration()]

- integrations: [new Sentry.BrowserTracing()]
+ integrations: [Sentry.browserTracingIntegration()]

Accessing integrations changed:

- const replay = Sentry.getIntegration(Replay);
+ const replay = Sentry.getClient().getIntegrationByName('Replay');

Performance Monitoring API Changes

The transaction-based API was replaced with OpenTelemetry-aligned span API:

- const transaction = Sentry.startTransaction({ name: 'my-transaction' });
- const span = transaction.startChild({ op: 'task' });
- span.finish();
- transaction.finish();
+ const result = Sentry.startSpan({ name: 'my-transaction' }, () => {
+   return Sentry.startSpan({ name: 'task', op: 'task' }, () => {
+     return doWork();
+   });
+ });

New span APIs:

• Sentry.startSpan() - Active span with callback (recommended)
• Sentry.startInactiveSpan() - Inactive span without callback
• Sentry.startSpanManual() - Manual span end control

Removed: startTransaction, span.startChild, scope.getSpan, scope.setSpan, getActiveTransaction

Scope API Changes

Hub Deprecation

In v8, Hub and getCurrentHub() still exist but are deprecated (fully removed in v9):

- const hub = Sentry.getCurrentHub();
- hub.captureException(error);
+ Sentry.captureException(error);

Config Option Changes

Node.js SDK Initialization Changes

v8 Node SDK uses OpenTelemetry, requiring early initialization. SDK must be initialized before other imports:

// Must be the first import
import * as Sentry from '@sentry/node';

Sentry.init({
  dsn: '__DSN__',
  tracesSampleRate: 1.0,
});

// Other imports after Sentry.init()
import express from 'express';

Express/Connect Handler Changes

- Sentry.Handlers.requestHandler()
- Sentry.Handlers.tracingHandler()
- Sentry.Handlers.errorHandler()
+ Sentry.setupExpressErrorHandler(app)  // Only error handler needed

- Sentry.Handlers.trpcMiddleware()
+ Sentry.trpcMiddleware()

Next.js Specific Changes

• withSentryConfig now takes 2 args (not 3). Plugin options and SDK options merged into second arg.
• sentry property in next.config.js removed. Use withSentryConfig second arg.
• New instrumentation.ts file required for server-side initialization.
• transpileClientSDK option removed (IE11 no longer supported).
• Removed: nextRouterInstrumentation, withSentryApi, withSentryGetServerSideProps, etc.

SvelteKit Specific Changes

• @sentry/vite-plugin upgraded from 0.x to 2.x
• sourceMapsUploadOptions restructured (release/sourcemaps nested objects)

Other Removed APIs

Grep Patterns to Find v7 Code

# Package imports that need updating
grep -rn "from '@sentry/hub'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"
grep -rn "from '@sentry/tracing'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"
grep -rn "from '@sentry/integrations'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"
grep -rn "from '@sentry/serverless'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"
grep -rn "from '@sentry/replay'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"
grep -rn "from '@sentry/angular-ivy'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"

# Deprecated API usage
grep -rn "new BrowserTracing\|new Replay\|new Integrations\." --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"
grep -rn "startTransaction\|\.startChild\b" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"
grep -rn "configureScope\|getCurrentHub\|addGlobalEventProcessor" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"
grep -rn "Handlers\.requestHandler\|Handlers\.tracingHandler\|Handlers\.errorHandler" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"
grep -rn "tracingOrigins" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"
grep -rn "Severity\." --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"

Migration Complexity Rating

Sentry JavaScript SDK: v8 to v9 Migration Reference

v9 focuses on API cleanup: removing deprecated v8 APIs, package consolidation, and dropping support for older runtimes. This update contains behavioral changes not caught by type checkers.

Compatible with Sentry self-hosted 24.4.2+ (unchanged from v8).

Version Support Changes

Framework Support Dropped

• Remix 1.x (minimum: 2.x)
• TanStack Router 1.63.0 and lower
• SvelteKit 1.x (minimum: 2.x)
• Ember.js 3.x and lower (minimum: 4.x)
• Prisma 5.x (default: 6.x, older via prismaInstrumentation option)

Package Consolidation

- import { something } from '@sentry/utils';
+ import { something } from '@sentry/core';

- import { SomeType } from '@sentry/types';
+ import { SomeType } from '@sentry/core';

Removed APIs — All SDKs (@sentry/core)

Hub Removal (Final)

getCurrentHub(), Hub, and getCurrentHubShim() are fully removed (were deprecated in v8).

Metrics API Removed

The Sentry metrics beta ended. The entire metrics API was removed from the SDK.

enableTracing Option Removed

  Sentry.init({
-   enableTracing: true,
+   tracesSampleRate: 1,
  });

autoSessionTracking Option Removed

To disable session tracking, remove browserSessionIntegration (browser) or configure httpIntegration with trackIncomingRequestsAsSessions: false (server).

transactionContext Flattened in Samplers

  Sentry.init({
    tracesSampler: samplingContext => {
-     if (samplingContext.transactionContext.name === '/health-check') {
+     if (samplingContext.name === '/health-check') {
        return 0;
      }
      return 0.5;
    },
  });

Also applies to profilesSampler.

Other Removed APIs

Removed APIs — Browser (@sentry/browser)

- Sentry.captureUserFeedback({
-   event_id: eventId,
-   name: 'User',
-   email: 'user@example.com',
-   comments: 'Something broke',
- });
+ Sentry.captureFeedback({
+   name: 'User',
+   email: 'user@example.com',
+   message: 'Something broke',
+   associatedEventId: eventId,
+ });

Removed APIs — Node (@sentry/node)

Integration Renames

Behavior Changes

• tracesSampler no longer called for every span (only root spans).
• requestDataIntegration no longer auto-sets user from request.user in Express. Use Sentry.setUser() manually.
• samplingContext.request removed; use samplingContext.normalizedRequest.
• skipOpenTelemetrySetup: true now auto-configures httpIntegration({ spans: false }).

Removed APIs — React (@sentry/react)

Removed APIs — NestJS (@sentry/nestjs)

Removed APIs — Vue (@sentry/vue)

Vue tracing options removed from Sentry.init(). Use vueIntegration() instead:

  Sentry.init({
-   tracingOptions: { trackComponents: true },
+   integrations: [
+     Sentry.vueIntegration({
+       tracingOptions: {
+         trackComponents: true,
+         timeout: 1000,
+         hooks: ['mount', 'update', 'unmount'],
+       },
+     }),
+   ],
  });

logErrors option removed from vueIntegration (error handler always propagates).

Removed APIs — Nuxt (@sentry/nuxt)

• tracingOptions in Sentry.init() removed. Use vueIntegration().
• stateTransformer in piniaIntegration now receives full state from all stores (top-level keys = store IDs).

Removed APIs — Next.js (@sentry/nextjs)

Behavior changes:

• Client source maps auto-deleted after upload (opt out via sourcemaps.deleteSourcemapsAfterUpload: false).
• Next.js Build ID no longer used as release fallback. Set release.name manually if needed.
• Source maps auto-enabled for both client and server builds.

Removed APIs — Other Frameworks

Behavior Changes — All SDKs

• beforeSendSpan: Cannot return null (dropping spans). Now also receives root spans.
• startSpan with custom scope: Scope is now cloned (was set directly in v8 for non-Node SDKs).
• tracesSampleRate: undefined now defers sampling to downstream SDKs.
• captureConsoleIntegration with attachStackTrace: true: Console messages now handled: true.
• Browser SDK no longer instructs backend to infer IP by default. Set sendDefaultPii: true to restore.

Behavior Changes — Vue/Nuxt

• Component tracking "update" spans no longer created by default. Add 'update' to tracingOptions.hooks to restore.

Type Changes

• Scope usages now require Scope instances (not interface-compatible objects).
• Client usages now require BaseClient instances. Abstract Client class removed.

Grep Patterns to Find v8 Code Needing Updates

# Package imports that need updating
grep -rn "from '@sentry/utils'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"
grep -rn "from '@sentry/types'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"

# Hub usage (fully removed)
grep -rn "getCurrentHub\|getCurrentHubShim\|new Hub(" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"

# Removed options
grep -rn "enableTracing\b" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"
grep -rn "autoSessionTracking\b" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"
grep -rn "hideSourceMaps\b" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"
grep -rn "autoInstrumentRemix\b" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"

# Removed methods
grep -rn "captureUserFeedback\b" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"
grep -rn "addOpenTelemetryInstrumentation\b" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"
grep -rn "transactionContext\b" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"

# Method renames
grep -rn "@WithSentry\b" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"
grep -rn "SentryGlobalGenericFilter\|SentryGlobalGraphQLFilter" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"
grep -rn "wrapUseRoutes[^V]" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"
grep -rn "wrapCreateBrowserRouter[^V]" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"
grep -rn "processThreadBreadcrumbIntegration" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"

# Metrics API (removed)
grep -rn "Sentry\.metrics\." --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"

# Vue/Nuxt tracing options at init level
grep -rn "tracingOptions.*trackComponents\|trackComponents.*true" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx"

Migration Complexity Rating

Sentry JavaScript SDK: v9 to v10 Migration Reference

v10 has not been released yet. This reference will be populated when the v10 migration guide is published.

Current Status

As of March 2026, v9 is the latest major version of the Sentry JavaScript SDK. No v10 migration guide exists yet.

Known v9 Deprecations (Likely Removed in v10)

These were deprecated in v9 and will likely be removed in v10:

- import { logger } from '@sentry/core';
- logger.info('message');
+ import { debug } from '@sentry/core';
+ debug.log('message');

Preparation

To prepare for v10: 1. Upgrade to latest v9 2. Fix all deprecation warnings 3. Replace @sentry/types imports with @sentry/core 4. Replace internal logger usage with debug

When v10 Is Released

Update this file with: 1. Version support changes 2. Removed APIs (from v9 deprecations) 3. Behavioral changes 4. Package changes 5. Migration grep patterns