feat(nextjs): Remove client.(server|client).config.ts functionality in favor of instrumentation.ts (#11059)

Author: Luca Forstner

MIGRATION.md

@@ -715,6 +715,56 @@ setup for source maps in Sentry and will not require you to match stack frame pa
 To see the new options, check out the docs at https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/,
 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.**
+
+The following is an example of how to initialize the serverside SDK in a Next.js instrumentation hook:
+
+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:
+
+   ```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...
+       });
+     }
+   }
+   ```
+
+   Note that you can initialize the SDK differently depending on which server runtime is being used.
+
+If you are using a
+[Next.js custom server](https://nextjs.org/docs/pages/building-your-application/configuring/custom-server), the
+`instrumentation.ts` 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.
+
+**Why are we making this change?** The very simple reason is that Next.js requires us to set up OpenTelemetry
+instrumentation inside the `register` function of the instrumentation hook. Looking a little bit further into the
+future, we also would like the Sentry SDK to be compatible with [Turbopack](https://turbo.build/pack), which is gonna be
+the bundler that Next.js will be using instead of Webpack. The SDK in its previous version depended heavily on Webpack
+in order to inject the `sentry.(server|edge).config.ts` files into the server-side code. Because this will not be
+possible in the future, we are doing ourselves a favor and doing things the way Next.js intends us to do them -
+hopefully reducing bugs and jank.
+
 ### Astro SDK
 
 #### Removal of `trackHeaders` option for Astro middleware

dev-packages/e2e-tests/test-applications/create-next-app/instrumentation.ts

@@ -0,0 +1,33 @@
+import * as Sentry from '@sentry/nextjs';
+
+declare global {
+  namespace globalThis {
+    var transactionIds: string[];
+  }
+}
+
+export function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    Sentry.init({
+      environment: 'qa', // dynamic sampling bias to keep transactions
+      dsn: process.env.NEXT_PUBLIC_E2E_TEST_DSN,
+      // Adjust this value in production, or use tracesSampler for greater control
+      tracesSampleRate: 1.0,
+      integrations: [Sentry.localVariablesIntegration()],
+    });
+
+    Sentry.addEventProcessor(event => {
+      global.transactionIds = global.transactionIds || [];
+
+      if (event.type === 'transaction') {
+        const eventId = event.event_id;
+
+        if (eventId) {
+          global.transactionIds.push(eventId);
+        }
+      }
+
+      return event;
+    });
+  }
+}

dev-packages/e2e-tests/test-applications/create-next-app/sentry.server.config.ts

@@ -0,0 +1,13 @@
+import * as Sentry from '@sentry/nextjs';
+
+export function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs' || process.env.NEXT_RUNTIME === 'edge') {
+    Sentry.init({
+      environment: 'qa', // dynamic sampling bias to keep transactions
+      dsn: process.env.NEXT_PUBLIC_E2E_TEST_DSN,
+      tunnel: `http://localhost:3031/`, // proxy server
+      tracesSampleRate: 1.0,
+      sendDefaultPii: true,
+    });
+  }
+}

dev-packages/e2e-tests/test-applications/nextjs-14/instrumentation.ts

@@ -0,0 +1,13 @@
+import * as Sentry from '@sentry/nextjs';
+
+export function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs' || process.env.NEXT_RUNTIME === 'edge') {
+    Sentry.init({
+      environment: 'qa', // dynamic sampling bias to keep transactions
+      dsn: process.env.NEXT_PUBLIC_E2E_TEST_DSN,
+      tunnel: `http://localhost:3031/`, // proxy server
+      tracesSampleRate: 1.0,
+      sendDefaultPii: true,
+    });
+  }
+}

dev-packages/e2e-tests/test-applications/nextjs-14/sentry.edge.config.ts

@@ -17,35 +17,64 @@
 
 ## Compatibility
 
-Currently, the minimum Next.js supported version is `10.0.8`.
+Currently, the minimum Next.js supported version is `11.2.0`.
 
 ## General
 
 This package is a wrapper around `@sentry/node` for the server and `@sentry/react` for the client, with added
 functionality related to Next.js.
 
-To use this SDK, init it in the Sentry config files.
+To use this SDK, initialize it in the Next.js configuration, in the `sentry.client.config.ts|js` file, and in the
+[Next.js Instrumentation Hook](https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation)
+(`instrumentation.ts|js`).
 
 ```javascript
-// sentry.client.config.js
+// next.config.js
+
+const { withSentryConfig } = require('@sentry/nextjs');
+
+const nextConfig = {
+  experimental: {
+    // The instrumentation hook is required for Sentry to work on the serverside
+    instrumentationHook: true,
+  },
+};
+
+// Wrap the Next.js configuration with Sentry
+module.exports = withSentryConfig(nextConfig);
+```
+
+```javascript
+// sentry.client.config.js or .ts
 
 import * as Sentry from '@sentry/nextjs';
 
 Sentry.init({
   dsn: '__DSN__',
-  // ...
+  // Your Sentry configuration for the Browser...
 });
 ```
 
 ```javascript
-// sentry.server.config.js
+// instrumentation.ts
 
 import * as Sentry from '@sentry/nextjs';
 
-Sentry.init({
-  dsn: '__DSN__',
-  // ...
-});
+export function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    Sentry.init({
+      dsn: '__DSN__',
+      // Your Node.js Sentry configuration...
+    });
+  }
+
+  if (process.env.NEXT_RUNTIME === 'edge') {
+    Sentry.init({
+      dsn: '__DSN__',
+      // Your Edge Runtime Sentry configuration...
+    });
+  }
+}
 ```
 
 To set context information or send manual events, use the exported functions of `@sentry/nextjs`.