Migrate from 7.x to 8.x

The main goal of version 8 is to improve our performance monitoring APIs, integrations API, and ESM support. This version is breaking because we removed deprecated APIs, restructured npm package contents, and introduced new dependencies on OpenTelemetry.

Before updating to 8.x of the SDK, we recommend upgrading to the latest version of 7.x. To fix all deprecations on 7.x, you can use the @sentry/migr8 codemod to automatically update your SDK usage. @sentry/migr8 requires Node 18+.

Copied
npx @sentry/migr8@latest

Our migration tool will let you select which updates to run, and automatically update your code. In some cases, we cannot automatically change code for you. These will be marked with a TODO(sentry) comment instead. Make sure to review all code changes after running @sentry/migr8!

Please see our detailed migration guide for more information on migrating from 7.x to 8.x.

8.x simplifies Sentry Next.js SDK initialization and leverages Next.js OpenTelemetry instrumentation for performance monitoring.

We recommend you read through all the Important Changes as they affect all Next.js SDK users. The Other Changes linked below only affect users who have very custom instrumentation. There is also a Troubleshooting section for common issues.

Sentry Next.js SDK 8.x supports:

Next.js version 13.2.0 or higher
Webpack 5.0.0 or higher
Node 14.18.0 or higher

If you need to support older versions of Next.js, please use Sentry Next.js SDK 7.x.

The client-side SDK now only works with ES2018 compatible browsers. The minimum supported browser versions are:

Chrome 63
Edge 79
Safari/iOS Safari 12
Firefox 58
Opera 50
Samsung Internet 8.2

For IE11 support please transpile your code to ES5 using babel or similar and add required polyfills.

With 8.x the Next.js SDK will no longer support the use of sentry.server.config.js|ts and sentry.edge.config.js|ts files. Instead, please initialize the Sentry Next.js SDK for the server-side in a Next.js instrumentation hook. Usage of sentry.client.config.ts|js is still supported and encouraged for initializing the client-side SDK.

To start using the Next.js built-in hooks, follow these steps:

First, enable the Next.js instrumentation hook by setting the experimental.instrumentationHook to true in your next.config.js.

Copied
module.exports = {
  experimental: {
    instrumentationHook: true,
  },
}

Next, create a instrumentation.ts|js file in the root directory of your project (or in the src folder if you have have one).
Now, export a register function from the instrumentation.ts|js file and call Sentry.init() inside of it:

Copied
import * as Sentry from '@sentry/nextjs';

export function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    // this is your Sentry.init call from `sentry.server.config.js|ts`
    Sentry.init({
      dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0',
      // Your Node.js Sentry configuration...
    });
  }

  // This is your Sentry.init call from `sentry.edge.config.js|ts`
  if (process.env.NEXT_RUNTIME === 'edge') {
    Sentry.init({
      dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0',
      // Your Edge Runtime Sentry configuration...
    });
  }
}

Last, you can delete the sentry.server.config.js|ts and sentry.edge.config.js|ts files. Please remember to keep your sentry.client.config.ts|js file for client-side SDK initialization.

If you are using a Next.js custom server, the instrumentation.ts|js hook is not called by Next.js so SDK instrumentation will not work as expected. See the troubleshooting section for more information.

The Custom Instrumentation API for Performance Monitoring has been revamped in 8.x. New methods have been introduced, and startTransaction and span.startChild has been removed. See the new Performance Monitoring APIs docs for more information.

With 8.x of the Sentry Next.js SDK, withSentryConfig will no longer accept 3 arguments. The second argument (holding options for the Sentry Webpack plugin) and the third argument (holding options for SDK build-time configuration) should now be passed as one:

Copied
const nextConfig = {
  // Your Next.js options...
};

-module.exports = withSentryConfig(
-  nextConfig,
-  {
-    // Your Sentry Webpack Plugin Options...
-  },
-  {
-    // Your Sentry SDK options...
-  },
-);
+module.exports = withSentryConfig(nextConfig, {
+  // Your Sentry Webpack Plugin Options...
+  // AND your Sentry SDK options...
+});

As part of this change the SDK will no longer support passing Next.js options with a sentry property to withSentryConfig. Please use the second argument of withSentryConfig to configure the SDK instead.

Copied
 const nextConfig = {
   // Your Next.js options...
-
-  sentry: {
-    // Your Sentry SDK options...
-  },
 };

 module.exports = withSentryConfig(nextConfig, {
   // Your Sentry Webpack Plugin Options...
+  // AND your Sentry SDK options...
 });

Under the hood, the Next.js SDK uses Sentry Webpack Plugin to upload sourcemaps and automatically associate add releases to your events. In 8.x, the SDK now uses 2.x of the Sentry Webpack Plugin which brings many improvements and bug fixes. Sourcemaps uploading with the Next.js SDK now uses Debug IDs.

The following previously deprecated API has been removed from the @sentry/nextjs package:

nextRouterInstrumentation has been removed in favour of browserTracingIntegration.

Copied
 import * as Sentry from '@sentry/nextjs';

 Sentry.init({
   dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0',
   integrations: [
-    new Sentry.Integrations.BrowserTracing({
-      routingInstrumentation: Sentry.nextRouterInstrumentation
-    }),
+    Sentry.browserTracingIntegration(),
   ]
 });

withSentryApi has been removed in favour of wrapApiHandlerWithSentry.

Copied
-import { withSentryApi } from "@sentry/nextjs";
+import { wrapApiHandlerWithSentry } from "@sentry/nextjs";

 const handler = (req, res) => {
   res.status(200).json({ name: "John Doe" });
 };

-export default withSentryApi(handler, "/api/myRoute");
+export default wrapApiHandlerWithSentry(handler, "/api/myRoute");

withSentryGetServerSideProps has been removed in favour of wrapGetServerSidePropsWithSentry.

Copied
-import { withSentryGetServerSideProps } from "@sentry/nextjs";
+import { wrapGetServerSidePropsWithSentry } from "@sentry/nextjs";

 export async function _getServerSideProps() {
   // Fetch data from external API
 }

-export const getServerSideProps = withSentryGetServerSideProps(_getServerSideProps);
+export const getServerSideProps = wrapGetServerSidePropsWithSentry(_getServerSideProps);

withSentryGetStaticProps has been removed in favour of wrapGetStaticPropsWithSentry.

Copied
-import { withSentryGetStaticProps } from "@sentry/nextjs";
+import { wrapGetStaticPropsWithSentry } from "@sentry/nextjs";

 export async function _getStaticProps() {
   // Fetch data from external API
 }

-export const getStaticProps = withSentryGetStaticProps(_getServerSideProps);
+export const getStaticProps = wrapGetStaticPropsWithSentry(_getServerSideProps);

withSentryServerSideGetInitialProps has been removed in favour of wrapGetInitialPropsWithSentry.

Copied
-import { withSentryServerSideGetInitialProps } from "@sentry/nextjs";
+import { wrapGetInitialPropsWithSentry } from "@sentry/nextjs";

 async function getInitialProps() {
   // Fetch data from external API
   return { data }
 }

-Page.getInitialProps = withSentryServerSideGetInitialProps(getInitialProps);
+Page.getInitialProps = wrapGetInitialPropsWithSentry(getInitialProps);

 export default function Page({ data }) {
   return data
 }

Similar to the above changes, the following API has been removed:

withSentryServerSideAppGetInitialProps has been removed in favour of wrapAppGetInitialPropsWithSentry.
withSentryServerSideDocumentGetInitialProps has been removed in favour of wrapDocumentGetInitialPropsWithSentry.
withSentryServerSideErrorGetInitialProps has been removed in favour of wrapErrorGetInitialPropsWithSentry.

The IS_BUILD and isBuild exports have been removed. There is no replacement for these exports.

The Next.js SDK now leverages Next.js OpenTelemetry instrumentation for performance monitoring. This means that the SDK will automatically capture OpenTelemetry data for your Next.js application without any additional configuration.

If you were previously using the @sentry/opentelemetry-node, it is no longer required and can be removed from your project. To migrate from using @sentry/opentelemetry-node to the Next.js SDK, follow these steps:

Make sure you've updated your SDK initialization as per the Updated SDK initialization section above.
Remove instrumenter: "otel", from your Sentry.init call for your server-side SDK initialization.

Copied
 import * as Sentry from '@sentry/nextjs';

 Sentry.init({
   dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0',
-  instrumenter: 'otel',
 });

Remove the @sentry/opentelemetry-node package and the instrumentation.node.js|ts file in your project. Make sure instrumentation.js|ts no longer imports the instrumentation.node.js|ts file.

To customize your OpenTelemetry setup, see the docs on OpenTelemetry instrumentation in 8.0.

The enableAnrDetection and Anr class exports have been removed the SDK. Instead you can now use the Sentry.anrIntegration to enable Application Not Responding detection

Copied
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  integrations: [
    Sentry.anrIntegration({ captureStackTrace: true })
  ],
});

The deepReadDirSync method has been removed as an export from the SDK. There is no replacement API.

The @sentry/replay package is no longer required. Instead you can import the relevant methods directly from your SDK. In addition to this, the integration is now functional instead of class-based.

Copied
-import { Replay } from '@sentry/replay';
-
 Sentry.init({
   dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0',
   integrations: [
-    new Replay(),
+    new Sentry.replayIntegration(),
   ],
 });

The xhr transport via makeXHRTransport transport has been removed. Only makeFetchTransport is available now. This means that the Sentry SDK requires the fetch API to be available in the environment.

@sentry/integrations has been removed and will no longer be published. We moved pluggable integrations from their own package (@sentry/integrations) to @sentry/nextjs. In addition they are now functions instead of classes.

Integrations that are now exported from @sentry/nextjs for client-side init:

httpClientIntegration (HTTPClient)
contextLinesIntegration (ContextLines)
reportingObserverIntegration (ReportingObserver)

Integrations that are now exported from @sentry/nextjs for client-side and server-side init:

captureConsoleIntegration (CaptureConsole)
debugIntegration (Debug)
extraErrorDataIntegration (ExtraErrorData)
rewriteFramesIntegration (RewriteFrames)
sessionTimingIntegration (SessionTiming)
dedupeIntegration (Dedupe) - Note: enabled by default, not pluggable

The Transaction integration has been removed from @sentry/integrations. There is no replacement API.

@sentry/hub has been removed and will no longer be published. All of the @sentry/hub exports have moved to @sentry/core or other related SDKs.

8.x of the Next.js SDK updates enforces usage of the instrumentation.ts file because it is a more flexible and powerful way to initialize the SDK, and allows us to use the Next.js built-in hooks and OpenTelemetry instrumentation. In addition it helps the SDK to be more compatible with the Turbopack which is not supported in Next.js SDK 7.x. The Next.js team recommends to use the instrumentation.ts file for SDK initialization, and we are working closely with them to ensure that the SDK works seamlessly with Next.js.

If you are using a Next.js custom server, the instrumentation.ts|js hook is not called by Next.js so you need to manually call it yourself from within your server code. It is recommended to do so as early as possible in your application lifecycle.

Here's an example of adding Sentry initialization code to the custom server example as per the Next.js documentation:

Copied
// make sure that Sentry is imported and initialized before any other imports.

+ const Sentry = require('@sentry/nextjs');
+
+ Sentry.init({
+   dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0',
+   // Your Node.js Sentry configuration...
+ })

const { createServer } = require('http')
const { parse } = require('url')
const next = require('next')

const dev = process.env.NODE_ENV !== 'production'
const hostname = 'localhost'
const port = 3000

const app = next({ dev, hostname, port })
const handle = app.getRequestHandler()

app.prepare().then(() => {
  createServer(async (req, res) => {
    // server code
  })
    .once('error', (err) => {
      // error code
    })
    .listen(port, () => {
      console.log(`> Ready on http://${hostname}:${port}`)
    })
})

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").

Suggest an edit to this page | Contribute to Docs | Report a problem

Package:: npm:@sentry/nextjs
Version:: 7.112.2
Repository:: https://github.com/getsentry/sentry-javascript

Docs

Sentry for Next.js

Distributed Tracing

Performance Monitoring

Metrics

Profiling

Session Replay

Crons

User Feedback

Migrate from 7.x to 8.x

Related Guides

Angular

Astro

AWS Lambda

Azure Functions

Bun

Capacitor

Connect

Cordova

Deno

Electron

Ember

Express

Fastify

Gatsby

Google Cloud Functions

Koa

Next.js

Node.js

React

Remix

Solid

Svelte

SvelteKit

Vue

Wasm