From 645276dffc29b4597e2c0afe47db77236af95302 Mon Sep 17 00:00:00 2001 From: Sergiy Dybskiy Date: Wed, 14 Jan 2026 16:59:53 -0500 Subject: [PATCH 1/5] docs(nextjs): Improve Session Replay platform-includes - Rewrite setup with SplitLayout for better readability - Add client-side only note in pre-requisites - Simplify install with skip-to-setup link - Keep privacy and lazy-loading sections with links Co-Authored-By: Claude Opus 4.5 --- .../install/javascript.nextjs.mdx | 4 +- .../pre-requisites/javascript.nextjs.mdx | 6 ++ .../setup/javascript.nextjs.mdx | 90 ++++++++++++++----- 3 files changed, 78 insertions(+), 22 deletions(-) create mode 100644 platform-includes/session-replay/pre-requisites/javascript.nextjs.mdx diff --git a/platform-includes/session-replay/install/javascript.nextjs.mdx b/platform-includes/session-replay/install/javascript.nextjs.mdx index 3050f964b7f1aa..55aa8a0dc9d116 100644 --- a/platform-includes/session-replay/install/javascript.nextjs.mdx +++ b/platform-includes/session-replay/install/javascript.nextjs.mdx @@ -1,5 +1,7 @@ -The Replay integration is already included with the Sentry SDK. We recommend installing the SDK through our installation wizard: +Session Replay is included with `@sentry/nextjs`. If you haven't installed Sentry yet, run the wizard: ```bash npx @sentry/wizard@latest -i nextjs ``` + +If you already have Sentry installed, skip to [Set Up](#set-up) below. diff --git a/platform-includes/session-replay/pre-requisites/javascript.nextjs.mdx b/platform-includes/session-replay/pre-requisites/javascript.nextjs.mdx new file mode 100644 index 00000000000000..16ac8d7f4973f6 --- /dev/null +++ b/platform-includes/session-replay/pre-requisites/javascript.nextjs.mdx @@ -0,0 +1,6 @@ +Session Replay requires `@sentry/nextjs` version `7.27.0` or higher. + + + Session Replay is **client-side only**. Configure it in + `instrumentation-client.ts`, not in server or edge config files. + diff --git a/platform-includes/session-replay/setup/javascript.nextjs.mdx b/platform-includes/session-replay/setup/javascript.nextjs.mdx index f1bc4524c22e59..622c9b30f08259 100644 --- a/platform-includes/session-replay/setup/javascript.nextjs.mdx +++ b/platform-includes/session-replay/setup/javascript.nextjs.mdx @@ -1,6 +1,20 @@ -On your client-side NextJS app, add: +Session Replay is configured in your **client-side** initialization file only. -```javascript {8,12,14-20} {filename:instrumentation-client.ts} + + + + + +#### Add Replay Integration + +Add `replayIntegration()` to your client initialization and configure the sample rates. + +**Testing tip:** Set `replaysSessionSampleRate: 1.0` during development to capture all sessions. + + + + +```typescript {filename:instrumentation-client.ts} import * as Sentry from "@sentry/nextjs"; Sentry.init({ @@ -14,34 +28,68 @@ Sentry.init({ // sessions when an error occurs. replaysOnErrorSampleRate: 1.0, - integrations: [ - Sentry.replayIntegration({ - // Additional SDK configuration goes in here, for example: - maskAllText: true, - blockAllMedia: true, - }), - ], + integrations: [Sentry.replayIntegration()], }); ``` -### Verify + + + + + + +#### Privacy Options -While you're testing, we recommend that you set `replaysSessionSampleRate` to `1.0`. This ensures that every user session will be sent to Sentry. +By default, Replay masks all text and blocks media. Customize privacy settings based on your needs. -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. +See Session Replay Privacy for all options. -### 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: +```typescript {filename:instrumentation-client.ts} +Sentry.replayIntegration({ + // Text masking (default: true) + maskAllText: true, + + // Block images/videos (default: true) + blockAllMedia: true, + + // Mask specific inputs + maskAllInputs: true, +}), +``` -- [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. -To learn more about session replay privacy, [read our docs.](/platforms/javascript/session-replay/privacy/) + + -### Lazy-loading Replay +#### Lazy-Loading Replay -Once you've added the integration, Replay will start automatically. If you don't want to start it immediately (lazy-load it), you can use `addIntegration`: +Load Replay only when needed instead of at startup. Useful for reducing initial bundle size. + + + + +```typescript {filename:instrumentation-client.ts} +// Don't add replayIntegration to init +Sentry.init({ + integrations: [], +}); + +// Later, when you want to start recording: +import("@sentry/nextjs").then((lazyLoadedSentry) => { + Sentry.addIntegration(lazyLoadedSentry.replayIntegration()); +}); +``` + + + + + + +### Verify - +Open your app, interact with it, then check [**Replays**](https://sentry.io/orgredirect/organizations/:orgslug/replays/) in Sentry to see your session. From b71e0b7ff1db204e30371b3d552ab7435751c387 Mon Sep 17 00:00:00 2001 From: Sergiy Dybskiy Date: Wed, 14 Jan 2026 17:32:30 -0500 Subject: [PATCH 2/5] docs(nextjs): Add dedicated Session Replay page with SplitLayout - Create Next.js-specific session-replay guide - Use SplitLayout for Canvas Recording, CSP, and Sampling sections - Simplified content focused on Next.js client-side config Co-Authored-By: Claude Opus 4.5 --- .../guides/nextjs/session-replay/index.mdx | 161 ++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 docs/platforms/javascript/guides/nextjs/session-replay/index.mdx diff --git a/docs/platforms/javascript/guides/nextjs/session-replay/index.mdx b/docs/platforms/javascript/guides/nextjs/session-replay/index.mdx new file mode 100644 index 00000000000000..3fd6e4b5f96a9a --- /dev/null +++ b/docs/platforms/javascript/guides/nextjs/session-replay/index.mdx @@ -0,0 +1,161 @@ +--- +title: Set Up Session Replay +sidebar_title: Session Replay +sidebar_order: 5 +description: "Learn how to enable Session Replay in your Next.js app." +--- + + + +[Session Replay](/product/explore/session-replay/) helps you get to the root cause of an error or latency issue faster by providing you with a video-like reproduction of what was happening in the user's browser before, during, and after the issue. + +By default, Session Replay masks all DOM text content, images, and user input. See Session Replay Privacy for customization options. + +## Pre-requisites + + + +## Install + + + +## Set Up + + + +### Canvas Recording + + + There is currently no PII scrubbing in canvas recordings! + + + + + + + +#### Enable Canvas Recording + +Add `replayCanvasIntegration()` to record HTML canvas elements. This is opt-in and tree-shaken if not used. + + + + + + + + + + + + +#### 3D and WebGL Canvases + +For 3D/WebGL canvases, enable manual snapshotting to avoid performance issues from `preserveDrawingBuffer`. + +Call `snapshot()` inside your paint loop, in the same execution loop as draw commands. + + + + +```typescript {filename:instrumentation-client.ts} +// Step 1: Enable manual snapshotting +Sentry.replayCanvasIntegration({ + enableManualSnapshot: true, +}); + +// Step 2: Call snapshot in your paint loop +function paint() { + const canvasRef = document.querySelector("#my-canvas"); + Sentry.getClient().getIntegrationByName("ReplayCanvas").snapshot(canvasRef); +} +``` + + + + + + +### Content Security Policy (CSP) + + + + + + +#### Configure CSP for Replay + +Session Replay uses a WebWorker for compression. Add these CSP entries to allow workers to load. + +Safari versions ≤ 15.4 also need `child-src`. + + + + +```text +worker-src 'self' blob: +child-src 'self' blob: +``` + + + + + + +If you can't update CSP, see [custom compression worker](/platforms/javascript/session-replay/configuration/#using-a-custom-compression-worker). + +## Sampling + +Sampling controls how much traffic results in a Session Replay. + + + + + + +#### Configure Sample Rates + +- **`replaysSessionSampleRate`** - Percentage of sessions to record fully +- **`replaysOnErrorSampleRate`** - Percentage of sessions to record when an error occurs (buffers 1 minute before the error) + +**Tip:** Keep `replaysOnErrorSampleRate` at `1.0` - error sessions provide the most debugging value. + + + + +```typescript {filename:instrumentation-client.ts} +Sentry.init({ + dsn: "___PUBLIC_DSN___", + + // Capture 10% of all sessions + replaysSessionSampleRate: 0.1, + + // Capture 100% of sessions with errors + replaysOnErrorSampleRate: 1.0, + + integrations: [Sentry.replayIntegration()], +}); +``` + + + + + + +### Recommended Production Sample Rates + +| Traffic Volume | Session Rate | Error Rate | +| ------------------------- | ------------ | ---------- | +| **High** (100k+/day) | `0.01` (1%) | `1.0` | +| **Medium** (10k-100k/day) | `0.1` (10%) | `1.0` | +| **Low** (<10k/day) | `0.25` (25%) | `1.0` | + +## Verify + +Set `replaysSessionSampleRate: 1.0` during testing. Open your app, interact with it, then check [**Replays**](https://sentry.io/orgredirect/organizations/:orgslug/replays/) in Sentry. + +**For production:** Lower `replaysSessionSampleRate` but keep `replaysOnErrorSampleRate` at `1.0`. + +## Next Steps + + From b93bf137ca53d53ce3cf82f8a829a6e493d4c498 Mon Sep 17 00:00:00 2001 From: Sergiy Dybskiy Date: Wed, 14 Jan 2026 22:08:57 -0500 Subject: [PATCH 3/5] fix: Escape < in table to avoid MDX parsing error --- .../javascript/guides/nextjs/session-replay/index.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/platforms/javascript/guides/nextjs/session-replay/index.mdx b/docs/platforms/javascript/guides/nextjs/session-replay/index.mdx index 3fd6e4b5f96a9a..afe65840a8bc20 100644 --- a/docs/platforms/javascript/guides/nextjs/session-replay/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/session-replay/index.mdx @@ -144,11 +144,11 @@ Sentry.init({ ### Recommended Production Sample Rates -| Traffic Volume | Session Rate | Error Rate | -| ------------------------- | ------------ | ---------- | -| **High** (100k+/day) | `0.01` (1%) | `1.0` | -| **Medium** (10k-100k/day) | `0.1` (10%) | `1.0` | -| **Low** (<10k/day) | `0.25` (25%) | `1.0` | +| Traffic Volume | Session Rate | Error Rate | +| -------------------------- | ------------ | ---------- | +| **High** (100k+/day) | `0.01` (1%) | `1.0` | +| **Medium** (10k-100k/day) | `0.1` (10%) | `1.0` | +| **Low** (under 10k/day) | `0.25` (25%) | `1.0` | ## Verify From 03c76f929d36b48c6372014becbd939bac6bb361 Mon Sep 17 00:00:00 2001 From: Sergiy Dybskiy Date: Wed, 14 Jan 2026 22:13:24 -0500 Subject: [PATCH 4/5] fix: Add optional chaining to ReplayCanvas snapshot example --- .../javascript/guides/nextjs/session-replay/index.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/platforms/javascript/guides/nextjs/session-replay/index.mdx b/docs/platforms/javascript/guides/nextjs/session-replay/index.mdx index afe65840a8bc20..7099e0caa14bf1 100644 --- a/docs/platforms/javascript/guides/nextjs/session-replay/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/session-replay/index.mdx @@ -67,7 +67,9 @@ Sentry.replayCanvasIntegration({ // Step 2: Call snapshot in your paint loop function paint() { const canvasRef = document.querySelector("#my-canvas"); - Sentry.getClient().getIntegrationByName("ReplayCanvas").snapshot(canvasRef); + Sentry.getClient() + ?.getIntegrationByName("ReplayCanvas") + ?.snapshot(canvasRef); } ``` From 95a161112924bcc96e33cb66aea2cff39fb0fc8f Mon Sep 17 00:00:00 2001 From: Sergiy Dybskiy Date: Wed, 14 Jan 2026 22:39:47 -0500 Subject: [PATCH 5/5] docs(nextjs): Move Session Replay to Features section, remove redundant Setup - Add sidebar_section: features to show in Features sidebar - Remove Set Up section (content is in platform-includes) Co-Authored-By: Claude Opus 4.5 --- .../javascript/guides/nextjs/session-replay/index.mdx | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/platforms/javascript/guides/nextjs/session-replay/index.mdx b/docs/platforms/javascript/guides/nextjs/session-replay/index.mdx index 7099e0caa14bf1..fae2ab99bcd8b2 100644 --- a/docs/platforms/javascript/guides/nextjs/session-replay/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/session-replay/index.mdx @@ -2,6 +2,7 @@ title: Set Up Session Replay sidebar_title: Session Replay sidebar_order: 5 +sidebar_section: features description: "Learn how to enable Session Replay in your Next.js app." --- @@ -19,10 +20,6 @@ By default, Session Replay masks all DOM text content, images, and user input. S -## Set Up - - - ### Canvas Recording