docs(nextjs): Improve Session Replay platform-includes #16020

sergical · 2026-01-14T22:00:13Z

https://linear.app/getsentry/issue/DEVEX-233/session-replay

DESCRIBE YOUR PR

Improves Next.js Session Replay documentation following patterns from #15936 and #15919:

Changes:

Rewrite setup/javascript.nextjs.mdx with SplitLayout for better readability
Add pre-requisites/javascript.nextjs.mdx with client-side only note
Update install/javascript.nextjs.mdx with skip-to-setup link
Keep privacy options and lazy-loading sections inline

Key improvement: Session Replay is client-side only for Next.js, now clearly documented with instrumentation-client.ts focus.

IS YOUR CHANGE URGENT?

Urgent deadline (GA date, etc.)
Other deadline
None: Not urgent, can wait up to 1 week+

PRE-MERGE CHECKLIST

Checked Vercel preview for correctness, including links
PR was reviewed and approved by any necessary SMEs (subject matter experts)
PR was reviewed and approved by a member of the Sentry docs team

Co-Authored-By: Claude Opus 4.5 [email protected]

vercel · 2026-01-14T22:00:18Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
develop-docs	Ready	Preview, Comment	Jan 22, 2026 10:04pm
sentry-docs	Ready	Preview, Comment	Jan 22, 2026 10:04pm

docs/platforms/javascript/guides/nextjs/session-replay/index.mdx

- 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 <[email protected]>

- 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 <[email protected]>

…nt 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 <[email protected]>

Delete 5 duplicate files (react, vue, svelte, ember, gatsby) that only differed by import statement. They now fall back to javascript.mdx which shows the correct SDK name dynamically via PlatformSdkPackageName. Co-Authored-By: Claude <[email protected]>

Falls back to common session-replay page now that platform-includes are consolidated. Co-Authored-By: Claude <[email protected]>

…locks - Add sdkPackage to CodeContext, computed from platform in DocPage - Handle ___SDK_PACKAGE___ replacement in makeKeywordsClickable - Update session-replay setup to use dynamic SDK package name Co-Authored-By: Claude <[email protected]>

src/components/codeKeywords/codeKeywords.tsx

Prevents the keyword from falling through to the generic handler which would render undefined/empty on non-platform pages. Co-Authored-By: Claude <[email protected]>

nikolovlazar · 2026-01-22T18:36:21Z

docs/platforms/javascript/common/session-replay/index.mdx


 To set up the integration, add the following to your Sentry initialization. There are several options you can pass to the integration constructor. See the [configuration documentation](/platforms/javascript/session-replay/configuration/) for more details.

+<PlatformSection supported={["javascript.nextjs"]}>


I don't see the PlatformSelection component in the preview. Is it because there's only "javascript.nextjs" being added to the supported prop?

its the alert here that specifies that in nextjs you only need to add session replay integration to `instrumentation-client.ts` vs all the configs

PlatformSection not selection 😅

Oh shoot it's Platform Section 😭

sfanahata · 2026-01-22T18:48:31Z

docs/platforms/javascript/common/session-replay/index.mdx

+</Alert>
+</PlatformSection>
+
 <PlatformContent


There seems to be a line in here that is now redundant from the line above: Session Replay is configured in your client-side initialization file only.

We're already saying that in the alert now.

good catch, removed from prerequisites since this alert is more contextual at the setup step, great catch!

nikolovlazar · 2026-01-22T18:48:54Z

docs/platforms/javascript/common/session-replay/index.mdx

+<PlatformSection supported={["javascript.nextjs"]}>
+<Alert>
+
+Session Replay only runs in the browser, so you only need to configure it in `instrumentation-client.ts`. The server (`instrumentation-server.ts`) and edge (`instrumentation-edge.ts`) entry points run in Node.js and Edge runtimes where Replay is not available.


For the server and edge, weren't these sentry.server.config.js and sentry.edge.config.js, being dynamically imported in instrumentation.js?

Good thing we caught it 😁

sfanahata · 2026-01-22T18:50:48Z

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

+
+</SplitLayout>
+
+### Verify


Why do we have 2 verify sections?

I suggest moving this additional content up to the higher verify section.

Oh, I see, this is in an includes. Hm. I think it's confusing to have twice. I also think the additional information toward the bottom is also more useful up here.

sfanahata

The JS and nextjs includes don't seem to be playing together altogether well. Two verify sections, PII maybe in a weird place. Just checked on a few frameworks and seeing duplications there too. Seeing some updates coming through so will wait to preview again.

- Use PlatformSection to show different content for vanilla JS vs framework SDKs - Add migration document link to Next.js prerequisites Co-Authored-By: Claude <[email protected]>

The base javascript.mdx fallback now handles this case. Co-Authored-By: Claude <[email protected]>

Co-Authored-By: Claude <[email protected]>

jaffrepaul · 2026-01-22T21:16:03Z

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

+
+</SplitLayout>
+
+### PII & Privacy Considerations


This should probably slide up under Privacy Options since it's related and Lazy loading is now between them in the flow.

great callout!

jaffrepaul · 2026-01-22T21:20:04Z

docs/platforms/javascript/common/session-replay/index.mdx

+### Recommended Production Sample Rates

-**Why keep `replaysOnErrorSampleRate` at 1.0?** Error sessions provide the most valuable debugging context, so capturing all of them is recommended regardless of traffic volume.
+| Traffic Volume             | Session Rate | Error Rate |


Was trimming the Description column intentional? Right column has a funny width without it.

yeah i think it's pretty self explanatory, but i think it also makes sense to put the table inside the left split view

sfanahata

Love it!

- Move PII & Privacy Considerations section to be directly after Privacy Options - Move sample rates table into the left side of the split view section Co-Authored-By: Claude <[email protected]>

jaffrepaul · 2026-01-22T21:50:58Z

src/components/codeKeywords/codeKeywords.tsx

 export const KEYWORDS_REGEX = /\b___(?:([A-Z_][A-Z0-9_]*)\.)?([A-Z_][A-Z0-9_]*)___\b/g;
 export const ORG_AUTH_TOKEN_REGEX = /___ORG_AUTH_TOKEN___/g;
+export const SDK_PACKAGE_REGEX = /___SDK_PACKAGE___/g;



I think you might have issues with these regex updates. You're not adding the issue but following some slippery patterns in this component. I was treading lightly in here awhile back when I added the index reset but this thing could use an overhaul. That's not part of this PR but, I'll point to some things that might cause problems:

The global flag on these regex's causes some downstream trickery and they probably don't need to be stateful at all

Add table-fit-content wrapper to remove min-width constraint on the last column, preventing unnecessary horizontal scroll. Co-Authored-By: Claude <[email protected]>

jaffrepaul · 2026-01-22T21:55:07Z

src/components/codeKeywords/codeKeywords.tsx


    if (ORG_AUTH_TOKEN_REGEX.test(child)) {
      makeOrgAuthTokenClickable(arr, child);
+    } else if (SDK_PACKAGE_REGEX.test(child)) {


.test & replace will both run the regex, I think (worth checking) you can just hit the replace without the test, cuz you it won't replace if there's no match.

Also might be worth setting '@sentry/browser' as a const. May not cause issues, but this feels scary 😀

codeowner-assignment bot requested review from a team January 14, 2026 22:00

sergical force-pushed the docs/nextjs-session-replay-improvements branch 2 times, most recently from cb61b61 to 645276d Compare January 14, 2026 22:03

vercel bot deployed to Preview – sentry-docs January 14, 2026 22:14 View deployment

sentry bot reviewed Jan 14, 2026

View reviewed changes

docs/platforms/javascript/guides/nextjs/session-replay/index.mdx Outdated Show resolved Hide resolved

vercel bot had a problem deploying to Preview – sentry-docs January 14, 2026 22:38 Failure

sergical force-pushed the docs/nextjs-session-replay-improvements branch from 9eea5d3 to 03c76f9 Compare January 15, 2026 03:14

vercel bot deployed to Preview – sentry-docs January 15, 2026 03:24 View deployment

vercel bot deployed to Preview – sentry-docs January 15, 2026 03:50 View deployment

sergical and others added 6 commits January 21, 2026 11:03

fix: Escape < in table to avoid MDX parsing error

62acef8

fix: Add optional chaining to ReplayCanvas snapshot example

e3218e9

docs(nextjs): Move Session Replay to Features section, remove redunda…

c167a4c

…nt 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 <[email protected]>

sergical force-pushed the docs/nextjs-session-replay-improvements branch from 95a1611 to 61123bc Compare January 21, 2026 17:43

sergical and others added 3 commits January 21, 2026 12:51

chore: Remove redundant Next.js Session Replay page

87bb5b5

Falls back to common session-replay page now that platform-includes are consolidated. Co-Authored-By: Claude <[email protected]>

[getsentry/action-github-commit] Auto commit

87e2f7a

sentry bot reviewed Jan 21, 2026

View reviewed changes

src/components/codeKeywords/codeKeywords.tsx Outdated Show resolved Hide resolved

vercel bot deployed to Preview – develop-docs January 21, 2026 18:03 View deployment

fix: Use fallback for ___SDK_PACKAGE___ when sdkPackage is null

8d6beac

Prevents the keyword from falling through to the generic handler which would render undefined/empty on non-platform pages. Co-Authored-By: Claude <[email protected]>

vercel bot deployed to Preview – develop-docs January 21, 2026 18:10 View deployment

vercel bot deployed to Preview – sentry-docs January 21, 2026 18:15 View deployment

nikolovlazar reviewed Jan 22, 2026

View reviewed changes

sergical requested a review from nikolovlazar January 22, 2026 18:42

sfanahata reviewed Jan 22, 2026

View reviewed changes

nikolovlazar reviewed Jan 22, 2026

View reviewed changes

sfanahata reviewed Jan 22, 2026

View reviewed changes

sergical added 2 commits January 22, 2026 14:00

Update server entry point reference in session replay docs

845677b

Remove unnecessary alert about Session Replay

1243298

sfanahata requested changes Jan 22, 2026

View reviewed changes

vercel bot deployed to Preview – sentry-docs January 22, 2026 19:12 View deployment

sergical and others added 3 commits January 22, 2026 14:53

Fix Session Replay prerequisites for framework SDKs

3bc1b87

- Use PlatformSection to show different content for vanilla JS vs framework SDKs - Add migration document link to Next.js prerequisites Co-Authored-By: Claude <[email protected]>

Remove redundant Next.js session replay prerequisites

b81199f

The base javascript.mdx fallback now handles this case. Co-Authored-By: Claude <[email protected]>

Remove redundant Verify sections from Session Replay setup

bce58cb

Co-Authored-By: Claude <[email protected]>

vercel bot deployed to Preview – sentry-docs January 22, 2026 20:11 View deployment

sergical requested review from nikolovlazar and sfanahata January 22, 2026 21:02

jaffrepaul reviewed Jan 22, 2026

View reviewed changes

sfanahata approved these changes Jan 22, 2026

View reviewed changes

Address remaining PR review comments

8d8a92a

- Move PII & Privacy Considerations section to be directly after Privacy Options - Move sample rates table into the left side of the split view section Co-Authored-By: Claude <[email protected]>

vercel bot deployed to Preview – sentry-docs January 22, 2026 21:46 View deployment

jaffrepaul reviewed Jan 22, 2026

View reviewed changes

Fix sample rates table width in split view

1d9e7e7

Add table-fit-content wrapper to remove min-width constraint on the last column, preventing unnecessary horizontal scroll. Co-Authored-By: Claude <[email protected]>

jaffrepaul reviewed Jan 22, 2026

View reviewed changes

vercel bot deployed to Preview – develop-docs January 22, 2026 21:59 View deployment

vercel bot deployed to Preview – sentry-docs January 22, 2026 22:04 View deployment


		To set up the integration, add the following to your Sentry initialization. There are several options you can pass to the integration constructor. See the [configuration documentation](/platforms/javascript/session-replay/configuration/) for more details.

		<PlatformSection supported={["javascript.nextjs"]}>


		</SplitLayout>

		### Verify

Uh oh!

docs(nextjs): Improve Session Replay platform-includes #16020

Are you sure you want to change the base?

docs(nextjs): Improve Session Replay platform-includes #16020

Conversation

sergical commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

DESCRIBE YOUR PR

IS YOUR CHANGE URGENT?

PRE-MERGE CHECKLIST

Uh oh!

vercel bot commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sfanahata left a comment

Choose a reason for hiding this comment

Uh oh!

jaffrepaul Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sfanahata left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

sergical commented Jan 14, 2026 •

edited

Loading

vercel bot commented Jan 14, 2026 •

edited

Loading

jaffrepaul Jan 22, 2026 •

edited

Loading