Refer to instrumentation-client.ts instead of sentry.client.config.ts for Next.js (#13311)

Author: Luca Forstner

docs/platforms/javascript/common/tracing/instrumentation/automatic-instrumentation.mdx

@@ -26,8 +26,7 @@ Capturing spans requires that you first <PlatformLink to="/tracing/">set up trac
 
 <PlatformSection supported={["javascript.nextjs"]} notSupported={["javascript"]}>
 
-Though the `BrowserTracing` integration is automatically enabled in `@sentry/nextjs`, in order to customize its options you must include it in your `Sentry.init` in `sentry.client.config.js`:
-
+Though the `BrowserTracing` integration is automatically enabled in `@sentry/nextjs`, in order to customize its options you must include it in your `Sentry.init` in `instrumentation-client.js`:
 
 ```javascript
 import * as Sentry from "@sentry/nextjs";
@@ -76,8 +75,8 @@ You will need to configure your web server [CORS](https://developer.mozilla.org/
 <PlatformContent includePath="performance/beforeNavigate-example" />
 
 <Alert>
-  If you're using React, read our docs to learn how to set up your
-  [React Router integration](/platforms/javascript/guides/react/configuration/integrations/react-router/).
+  If you're using React, read our docs to learn how to set up your [React Router
+  integration](/platforms/javascript/guides/react/configuration/integrations/react-router/).
 </Alert>
 
 ### shouldCreateSpanForRequest
@@ -131,8 +130,11 @@ This option determines whether spans for long tasks automatically get created.
 The default is `true`.
 
 ### enableLongAnimationFrame
+
 <Alert>
-The `enableLongAnimationFrame` option requires SDK [version 8.18.0](https://github.com/getsentry/sentry-javascript/releases/tag/8.18.0) or higher.
+  The `enableLongAnimationFrame` option requires SDK [version
+  8.18.0](https://github.com/getsentry/sentry-javascript/releases/tag/8.18.0) or
+  higher.
 </Alert>
 
 This option determines whether spans for long animation frames get created automatically. If both `enableLongAnimationFrame` and `enableLongTask` are enabled, Sentry will send long animation frames and fallback to long tasks (if long animation frames aren't supported by the browser).
@@ -142,7 +144,9 @@ The default is `true`.
 ### enableInp
 
 <Alert>
-The `enableInp` option requires SDK [version 7.104.0](https://github.com/getsentry/sentry-javascript/releases/tag/7.104.0) or higher.
+  The `enableInp` option requires SDK [version
+  7.104.0](https://github.com/getsentry/sentry-javascript/releases/tag/7.104.0)
+  or higher.
 </Alert>
 
 This option determines whether interactions spans automatically get created when an [Interaction to Next Paint (INP)](/product/insights/web-vitals/web-vitals-concepts/#interaction-to-next-paint-inp) event is detected. Interactions are scored and surfaced in the [Web Vitals](/product/insights/web-vitals/) module.
@@ -153,6 +157,7 @@ The default is `true` in `8.x` of the SDK, and `false` in `7.x`.
 INP samples currently incur no cost to enable at Sentry. Basic samples contain limited information such as the interaction target, latency, and user. You may wish to enrich your INP samples by setting up [Session Replays](/platforms/javascript/session-replay/) and/or setting up [Browser Profiling](/platforms/javascript/profiling/) instrumentation around your interactive elements to gain further insights into your slowest interactions.
 
 Please note that any Session Replays and Browser Profiles used this way will incur their [standard cost](/pricing/#per-category-pricing) depending on your plan and are subject to the sampling rates configured.
+
 </Alert>
 
 <PlatformContent includePath="performance/enable-inp-example" />

docs/platforms/javascript/guides/nextjs/manual-setup.mdx

@@ -100,16 +100,19 @@ export default withSentryConfig(nextConfig, {
 
 ### Initialize Sentry Client-Side and Server-Side SDKs
 
-Create three files in your application's root directory: `sentry.client.config.(js|ts)`, `sentry.server.config.(js|ts)` and `sentry.edge.config.(js|ts)`. Add the following initialization code into each respective file:
+Create three files in your application's root directory: `sentry.server.config.(js|ts)`, `sentry.edge.config.(js|ts)`, and `instrumentation-client.(js|ts)`. Add the following initialization code into each respective file:
 
 <Alert level="info" title="Note">
   These files run in different environments (browser, server, edge) and are
   slightly different, so copy them carefully.
 </Alert>
 
-```javascript {tabTitle:Client} {filename:sentry.client.config.(js|ts)} {"onboardingOptions": {"performance": "7-13", "session-replay": "5-6, 14-20"}}
+```javascript {tabTitle:Client} {filename:instrumentation-client.(js|ts)} {"onboardingOptions": {"performance": "7-13", "session-replay": "5-6, 14-20"}}
 import * as Sentry from "@sentry/nextjs";
 
+// This export will instrument router navigations. `captureRouterTransitionStart` is available from SDK version 9.12.0 onwards - upgrade if necessary!
+export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;
+
 Sentry.init({
   dsn: "___PUBLIC_DSN___",
   // Replay may only be enabled for the client-side
@@ -575,7 +578,7 @@ module.exports = withSentryConfig(nextConfig, {
 
 ### Opt Out of Sentry SDK bundling in Client- or Server-Side
 
-If you want the Sentry SDK to be available in your server-side and not in client-side, you can simply delete `sentry.client.config.js`. This will prevent webpack from pulling in the Sentry related files when generating the browser bundle.
+If you want the Sentry SDK to be available in your server-side and not in client-side, you can simply delete `instrumentation-client.(js|ts)`. This will prevent webpack from pulling in the Sentry related files when generating the browser bundle.
 Similarly, to opt out of server-side SDK bundling, you can simply delete the `sentry.server.config.js` and `sentry.edge.config.js` files. Make sure to remove any imports of these files from `instrumentation.ts`.
 
 ## Step 8: Instrument Vercel Cron Jobs (Optional)

platform-includes/configuration/integrations/javascript.nextjs.mdx

@@ -3,7 +3,7 @@ However, it's important to note that not all integrations are compatible with al
 
 Depending on whether an integration enhances the functionality of a particular runtime, such as the BrowserTracing integration for the browser runtime or the RequestData integration for the Node.js.js runtime, you can only include these integrations in their respective configuration files:
 
-- For the browser runtime, add integrations to `sentry.client.config.(js|ts)`.
+- For the browser runtime, add integrations to `instrumentation-client.(js|ts)`.
 - For Node.js.js, add integrations to your Sentry setup in `instrumentation.(js|ts)`.
 - For the Edge runtime, add integrations to your Sentry setup in `instrumentation.(js|ts)`.
 

platform-includes/configuration/integrations/lazy-loading-replay/javascript.nextjs.mdx

@@ -1,11 +1,11 @@
-```javascript {filename:sentry.client.config.ts}
+```javascript {filename:instrumentation-client.ts}
 Sentry.init({
   // Note, Replay is NOT instantiated below:
   integrations: [],
 });
 
 // Sometime later
-import("@sentry/nextjs").then(lazyLoadedSentry => {
+import("@sentry/nextjs").then((lazyLoadedSentry) => {
   Sentry.addIntegration(lazyLoadedSentry.replayIntegration());
 });
 ```

platform-includes/distributed-tracing/how-to-use/javascript.nextjs.mdx

@@ -4,14 +4,14 @@ For client-side, when you are interacting with other external API systems, you m
 
 <Alert>
 
-Note: port numbers are relevant for trace propagation and the origin. You may need to configure the `tracePropagationTargets` to ensure that traces are propagated across your services if they run on different ports. 
+Note: port numbers are relevant for trace propagation and the origin. You may need to configure the `tracePropagationTargets` to ensure that traces are propagated across your services if they run on different ports.
 
 For example, if you have a Node.js backend running locally on port 3000, that destination (`http://localhost:3000`) should be added to the `tracePropagationTargets` array on your frontend to ensure that CORS doesn't restrict the propagation of traces.
 
 </Alert>
 
 ```javascript
-// sentry.client.config.js
+// instrumentation-client.js
 Sentry.init({
   dsn: "___PUBLIC_DSN___",
   integrations: [Sentry.browserTracingIntegration()],
@@ -26,7 +26,7 @@ If you're using version `7.57.x` or below, you'll need to have our <PlatformLink
 #### Example 1: Microservices E-commerce Platform
 
 ```javascript
-// sentry.client.config.js
+// instrumentation-client.js
 Sentry.init({
   dsn: "___PUBLIC_DSN___",
   integrations: [Sentry.browserTracingIntegration()],
@@ -39,15 +39,15 @@ Sentry.init({
 
 This tells Sentry to pass trace headers across the following paths:
 
-* Your main API server (where product data comes from)
-* Your authentication server (where logins happen)
+- Your main API server (where product data comes from)
+- Your authentication server (where logins happen)
 
 This way, if a customer experiences an error during checkout, or you want to check the performance of a specific endpoint, you can see the complete path their request took across these different services.
 
 #### Example 2: Mobile App with Backend Services
 
 ```javascript
-// sentry.client.config.js
+// instrumentation-client.js
 Sentry.init({
   dsn: "___PUBLIC_DSN___",
   integrations: [Sentry.browserTracingIntegration()],
@@ -56,16 +56,16 @@ Sentry.init({
   tracePropagationTargets: [
     "https://api.myapp.com",
     "https://media.myapp.com",
-    /^\/local-api\//
+    /^\/local-api\//,
   ],
 });
 ```
 
 This configuration lets your app track user actions across:
 
-* Your main API server (handles most app functions)
-* Your media server (handles images, videos, etc.)
-* Any local API endpoints in your app
+- Your main API server (handles most app functions)
+- Your media server (handles images, videos, etc.)
+- Any local API endpoints in your app
 
 If your app crashes while a user is uploading a photo, you can trace exactly where the problem occurred - in the app itself, the main API, or the media service.
 

platform-includes/migration/javascript-v8/v7-deprecation/javascript.nextjs.mdx

@@ -59,7 +59,7 @@ Server-side Integrations:
 
 Browser tracing is automatically set up for you in these packages so you do not need to change you code unless you were using the `BrowserTracing` class directly.
 
-```JavaScript {filename:sentry.client.config.js} diff
+```JavaScript {filename:instrumentation-client.js} diff
  import * as Sentry from "@sentry/nextjs";
 
  Sentry.init({

platform-includes/performance/configure-sample-rate/javascript.nextjs.mdx

@@ -1,5 +1,4 @@
-Set `tracesSampleRate` in your config files, `sentry.server.config.js`, `sentry.client.config.js`, and `sentry.edge.config.js`:
-
+Set `tracesSampleRate` in your config files, `instrumentation-client.js`, `sentry.server.config.js`, and `sentry.edge.config.js`:
 
 ```javascript
 import * as Sentry from "@sentry/nextjs";

platform-includes/profiling/automatic-instrumentation-setup/javascript.nextjs.mdx

@@ -1,4 +1,4 @@
-```javascript {filename:sentry.client.config.js|ts}
+```javascript {filename:instrumentation-client.js|ts}
 import * as Sentry from "@sentry/nextjs";
 
 Sentry.init({
@@ -26,7 +26,7 @@ Sentry.init({
 
 Alternatively, instead of a `profilesSampleRate` your can also provide a `profilesSampler` function:
 
-```javascript {filename:sentry.client.config.js|ts}
+```javascript {filename:instrumentation-client.js|ts}
 import * as Sentry from "@sentry/nextjs";
 
 Sentry.init({

platform-includes/session-replay/setup/javascript.nextjs.mdx

@@ -1,6 +1,6 @@
 On your client-side NextJS app, add:
 
-```javascript {8,12,14-20} {filename:sentry.client.config.ts}
+```javascript {8,12,14-20} {filename:instrumentation-client.ts}
 import * as Sentry from "@sentry/nextjs";
 
 Sentry.init({
@@ -30,11 +30,11 @@ While you're testing, we recommend that you set `replaysSessionSampleRate` to `1
 
 Once testing is complete, **we recommend lowering this value in production**. We still recommend keeping `replaysOnErrorSampleRate` set to `1.0`, so that, whenever possible, every error has an associated replay with additional debugging context.
 
-
 ### PII & Privacy Considerations
 
 Personally identifiable information (PII), and privacy are important considerations when enabling Session Replay. There are multiple ways in which Sentry helps you avoid collecting PII, including:
-- [Masking](/platforms/javascript/session-replay/privacy/#masking), which replaces the text content with something else. (The default behavior being to replace each character with a *.)
+
+- [Masking](/platforms/javascript/session-replay/privacy/#masking), which replaces the text content with something else. (The default behavior being to replace each character with a \*.)
 - Making [Network request, response bodies, and headers](/platforms/javascript/session-replay/privacy/#network-request-and-response-bodies-and-headers) an opt-in feature, because the best way to avoid getting PII into Sentry is by not adding URLs of endpoints that may contain PII.
 
 While we have certain privacy considerations in place, Sentry's Session Replays allow you to set up the [privacy configurations](/platforms/javascript/session-replay/privacy/#privacy-configuration) that work best for your use case. For example, if you're working on a static website that's free of PII or other types of private data, you can opt out of the default text masking and image blocking settings.

platform-includes/tracing/sample-rate/javascript.nextjs.mdx

@@ -1,9 +1,9 @@
 ```javascript
-// sentry.client.config.js
+// instrumentation-client.js
 Sentry.init({
   dsn: "___PUBLIC_DSN___",
   integrations: [Sentry.browserTracingIntegration()],
   // Capture 25% of all transactions
-  tracesSampleRate: 0.25
+  tracesSampleRate: 0.25,
 });
-```
+```