Skip to content

Commit

Permalink
docs: Fix Next.js migration guide for v8 (#14817)
Browse files Browse the repository at this point in the history
  • Loading branch information
lforst authored Jan 7, 2025
1 parent b8c83be commit ed8d23c
Showing 1 changed file with 18 additions and 36 deletions.
54 changes: 18 additions & 36 deletions MIGRATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -870,53 +870,35 @@ or look at the TypeScript type definitions of `withSentryConfig`.
#### Updated the recommended way of calling `Sentry.init()`
With version 8 of the SDK we will no longer support the use of `sentry.server.config.ts` and `sentry.edge.config.ts`
files. Instead, please initialize the Sentry Next.js SDK for the serverside in a
[Next.js instrumentation hook](https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation).
**`sentry.client.config.ts|js` is still supported and encouraged for initializing the clientside SDK.**
Version 8 of 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).
The following is an example of how to initialize the serverside SDK in a Next.js instrumentation hook:
To start using the Next.js instrumentation hook, follow these steps:
1. First, enable the Next.js instrumentation hook by setting the `experimental.instrumentationHook` to `true` in your
`next.config.js`.
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:
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)
```ts
import * as Sentry from '@sentry/nextjs';

export function register() {
if (process.env.NEXT_RUNTIME === 'nodejs') {
Sentry.init({
dsn: 'YOUR_DSN',
// Your Node.js Sentry configuration...
});
}

if (process.env.NEXT_RUNTIME === 'edge') {
Sentry.init({
dsn: 'YOUR_DSN',
// Your Edge Runtime Sentry configuration...
});
}
```JavaScript {filename:next.config.js} {2-4}
module.exports = {
experimental: {
instrumentationHook: true, // Not required on Next.js 15+
},
}
```
If you need to import a Node.js specific integration (like for example `@sentry/profiling-node`), you will have to
import the package using a dynamic import to prevent Next.js from bundling Node.js APIs into bundles for other
runtime environments (like the Browser or the Edge runtime). You can do so as follows:
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 import your `sentry.server.config.js|ts` and `sentry.edge.config.js|ts` modules:
```ts
```JavaScript {filename:instrumentation.js}
import * as Sentry from '@sentry/nextjs';

export async function register() {
if (process.env.NEXT_RUNTIME === 'nodejs') {
const { nodeProfilingIntegration } = await import('@sentry/profiling-node');
Sentry.init({
dsn: 'YOUR_DSN',
integrations: [nodeProfilingIntegration()],
});
await import('./sentry.server.config');
}

if (process.env.NEXT_RUNTIME === 'edge') {
await import('./sentry.edge.config');
}
}
```
Expand Down

0 comments on commit ed8d23c

Please # to comment.