Session Replay for React Apps — Setup, SPA Routing, and Debugging Guide

React apps are hard to understand from analytics alone. Users don't load pages—they trigger state changes, open modals, and navigate client-side. When a user says "it didn't work," a pageview count is useless. Session replay shows the exact sequence of UI states, plus console errors and network calls, so you can see what happened.

Table of Contents

1. How Replay Works in a React App
2. Installation
3. Route Changes in SPAs
4. Identify Users and Track Events
5. Mask Sensitive Components
6. Debugging With Replay
7. Performance Considerations
8. Key Takeaways

How Replay Works in a React App

Replay tools don't record video. They capture an initial DOM snapshot, then record mutations (React re-renders), input events, scrolls, and clicks. During playback the DOM is rebuilt in an iframe. That's why replays are sharp and lightweight—and why React's virtual DOM doesn't matter: the tool sees the real DOM React produces.

Installation

The simplest approach is the script tag in your index.html head. Load it async so it never blocks your bundle. For Vite, CRA, or any React SPA, follow Install in React—it covers both script-tag and in-app initialization patterns.

Route Changes in SPAs

Client-side routers (React Router, TanStack Router, Wouter) change the URL with the History API instead of loading new pages. DeepSync hooks history changes automatically, so each route appears as a page in the session timeline, in heatmaps, and in funnels—no manual page tracking needed. More on this in session replay for single-page applications.

Identify Users and Track Events

After login, associate the session with your user ID so support can find "the session where Priya couldn't upload a file." Track key actions as custom events (signup completed, project created, upgrade clicked) to use as goals and funnel steps. See the SDK API reference.

Mask Sensitive Components

Passwords, payment fields, and text inputs are masked by default at capture time. For anything else—account balances, names in a table, health data—add the masking class to the element. Elements with the block class aren't recorded at all. Details: PII masking.

<div class="ds-mask">Account balance: ₹48,200</div>

Debugging With Replay

1. Start from the error. Open JavaScript Errors, sorted by affected sessions.
2. Jump into a replay where the error occurred.
3. Read the timeline: user click → network request → failed response → console error → UI state.
4. Reproduce locally with the exact steps, browser, and viewport.

Full workflow: how to reproduce bugs with session replay.

Performance Considerations

• Load the script async.
• Large lists with constant re-renders produce more mutation data—virtualize long lists (good for users too).
• Avoid recording internal/staging environments to save quota.
• Use real-user Core Web Vitals to confirm there's no regression.

Key Takeaways

• Replay records the real DOM React renders—no special React integration needed.
• Route changes are tracked automatically in SPAs.
• Identify users and track key events for searchable sessions and funnels.
• Mask sensitive components with a class.

Conclusion

React made UIs dynamic. Session replay makes them observable. Install it once and every "it doesn't work" ticket becomes a five-minute investigation.

Start free · Install in React · Next.js guide