Skip to main content
How-to

Adding session replay to a React app.

Updated 2026-05-26 Relyv.ai Editorial Team

Five-minute install for any React app — Create React App, Vite, Remix, or plain Webpack. The SDK is tree-shaken, fully typed, and runs entirely off the main thread. Here's the code.

Try Relyv free See the SDK
TL;DR
Install @relyv/sdk via npm, call init({ apiKey, projectId }) once in your top-level entry (main.tsx, index.tsx, root.layout.tsx), tag PII fields with data-relyv-mask, deploy. The SDK auto-captures clicks, network calls, console errors, and DOM mutations from the first render; React-specific concerns (StrictMode double-render, error boundaries, route changes) are handled automatically.

The one-line answer

Install @relyv/sdk via npm, call init({ apiKey, projectId }) once at app entry, and the SDK records every session from first render — including network calls, console errors, and DOM mutations — with ~14 KB gzipped and sub-1% main-thread overhead.

What you need before starting

Three prerequisites:

  • <strong>A Relyv account</strong> (free tier covers 1,000 sessions/mo).
  • <strong>API key + project ID</strong> from dashboard.relyv.ai → Settings → API keys.
  • <strong>Edit access to your React app entry file</strong> (main.tsx, index.tsx, or equivalent).

How Relyv React setup works

The SDK is framework-agnostic but behaves correctly inside React out of the box. It hooks the History API for route-change detection (works with React Router, TanStack Router, Wouter), captures the initial DOM after first paint, and subscribes to MutationObserver for every subsequent change. StrictMode's double-render doesn't cause duplicate sessions — the SDK deduplicates on session ID, not init calls.

Step-by-step

  1. 1

    Install the SDK

    Run npm install @relyv/sdk (or pnpm add @relyv/sdk / yarn add @relyv/sdk / bun add @relyv/sdk). The package is fully typed; types are exported alongside the runtime.

  2. 2

    Initialise at app entry

    Add one import + one init call to your top-level entry file:

    // main.tsx (Vite) or index.tsx (CRA)
import { init } from '@relyv/sdk';

init({
  apiKey: import.meta.env.VITE_RELYV_API_KEY,
  projectId: import.meta.env.VITE_RELYV_PROJECT_ID,
});

// rest of your render code
ReactDOM.createRoot(...).render(...);

    Init must run on the client (in the browser), not at build time. Vite + CRA satisfy this automatically because main.tsx runs in the browser.

  3. 3

    Mark sensitive fields

    Add the data-relyv-mask attribute to any element rendering PII the SDK can't identify by content alone:

    <input data-relyv-mask name="customer-id" />
<div data-relyv-mask>{user.fullName}</div>

    Standard PII (emails, phone numbers, credit cards) is masked automatically via regex + Luhn validation — no marker needed.

  4. 4

    Verify in dev before deploying

    Run your app locally, click around for 30 seconds, then open the Relyv Library at dashboard.relyv.ai. The session appears within seconds. Watch the replay end-to-end, open the Network and Console tabs inside the replay viewer, and confirm no PII leaks. Check the "raw payload" tool in Settings if you want to see the exact serialized capture.

  5. 5

    Deploy + monitor

    Push to staging, watch the session corpus grow, look for the first AI-summarised bug ticket in the Triage inbox within a few hours. Production deploy follows the same pattern; no per-environment configuration beyond the API key/project ID for the corresponding workspace.

Frequently asked questions

Does this work with React 19 and the new compiler?

Yes. The SDK doesn't depend on React internals — it operates on the DOM and the History API, both of which the React Compiler doesn't touch. Tested against React 18.3, 19.0, and the Compiler beta.

What about React Server Components / Next.js App Router?

See the Next.js-specific guide (link below). Short version: wrap the init call in a Client Component that mounts once at app root, so it only runs in the browser, not during SSR/RSC streaming.

Does it duplicate sessions in StrictMode?

No. The SDK is idempotent — calling init twice with the same apiKey/projectId creates one session, not two. StrictMode's double-render is fully supported.

How do I capture state from Redux / Zustand / Jotai?

The SDK auto-captures the DOM, network, and console. For state-store snapshots, register a state plugin: import { reduxPlugin } from '@relyv/sdk/plugins'; init({ ..., plugins: [reduxPlugin(store)] }). Plugins exist for Redux, Zustand, Pinia, and Jotai; custom plugins follow a documented interface.

Will it break my CSP?

The SDK loads from a same-origin path if you use npm + bundling (no CSP changes needed). If you use the CDN tag instead (cdn.relyv.ai/sdk/v1/relyv.js), allowlist cdn.relyv.ai in your script-src and ingest-relyv.ai in connect-src.

What about React Native?

React Native has different capture mechanics (no DOM). Native iOS and Android SDKs are in alpha; cross-platform via React Native bridge is on the roadmap. For now, React Native apps are best served by the in-app feedback flow + screenshot capture rather than full DOM replay.

Does it slow down CSR/SSR hydration?

No measurable hydration regression in our benchmarks. The SDK's init schedules its initial DOM snapshot in a requestIdleCallback (or setTimeout 0 fallback), so it never blocks the first interactive frame. Main-thread overhead during ongoing capture is under 1% on production traffic.

Related reading

Ready to record your first session?

Free 1,000 sessions/mo. No credit card. Cancel anytime, no refunds.

Try Relyv free