diff --git a/platform-includes/migration/javascript-v8/important-changes/javascript.nextjs.mdx b/platform-includes/migration/javascript-v8/important-changes/javascript.nextjs.mdx index 0ebeef389673b..640024ef2f3c0 100644 --- a/platform-includes/migration/javascript-v8/important-changes/javascript.nextjs.mdx +++ b/platform-includes/migration/javascript-v8/important-changes/javascript.nextjs.mdx @@ -12,48 +12,39 @@ If you need to support older versions of Node.js or Next.js, please use Sentry N ### Updated SDK initialization -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](https://nextjs.org/docs/app/api-reference/file-conventions/instrumentation). Usage of `sentry.client.config.ts|js` is still supported and encouraged for initializing the client-side SDK. +With `8.x` the Next.js SDK will require an additional `instrumentation.ts` file to execute the `sentry.server.config.js|ts` and `sentry.edge.config.js|ts` modules to initialize the SDK for the server-side. +The `instrumentation.ts` file is a Next.js native API called [instrumentation hook](https://nextjs.org/docs/app/api-reference/file-conventions/instrumentation). -To start using the Next.js built-in hooks, follow these steps: +To start using the Next.js instrumentation hook, follow these steps: -1. First, enable the Next.js instrumentation hook by setting the [`experimental.instrumentationHook`](https://nextjs.org/docs/app/api-reference/next-config-js/instrumentationHook) to true in your `next.config.js`. +1. First, enable the Next.js instrumentation hook by setting the [`experimental.instrumentationHook`](https://nextjs.org/docs/app/api-reference/next-config-js/instrumentationHook) to true in your `next.config.js`. (This step is no longer required with Next.js 15) ```JavaScript {filename:next.config.js} {2-4} module.exports = { experimental: { - instrumentationHook: true, + instrumentationHook: true, // Not required on Next.js 15+ }, } ``` 2. Next, create a `instrumentation.ts|js` file in the root directory of your project (or in the src folder if you have have one). -3. Now, export a register function from the `instrumentation.ts|js` file and call `Sentry.init()` inside of it: +3. Now, export a register function from the `instrumentation.ts|js` file and import your `sentry.server.config.js|ts` and `sentry.edge.config.js|ts` modules: ```JavaScript {filename:instrumentation.js} import * as Sentry from '@sentry/nextjs'; -export function register() { +export async function register() { if (process.env.NEXT_RUNTIME === 'nodejs') { - // this is your Sentry.init call from `sentry.server.config.js|ts` - Sentry.init({ - dsn: '___PUBLIC_DSN___', - // Your Node.js Sentry configuration... - }); + await import('./sentry.server.config'); } - // This is your Sentry.init call from `sentry.edge.config.js|ts` if (process.env.NEXT_RUNTIME === 'edge') { - Sentry.init({ - dsn: '___PUBLIC_DSN___', - // Your Edge Runtime Sentry configuration... - }); + await import('./sentry.edge.config'); } } ``` -4. 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](https://nextjs.org/docs/pages/building-your-application/configuring/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](#nextjs-custom-server) for more information.