Skip to content

Commit

Permalink
Fix v8 migration guide for Next.js to align with wizard (#12195)
Browse files Browse the repository at this point in the history
  • Loading branch information
lforst authored Jan 7, 2025
1 parent 837e0f9 commit 903a8f7
Showing 1 changed file with 9 additions and 18 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<Alert level="warning">

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.
Expand Down

0 comments on commit 903a8f7

Please sign in to comment.