Session Replay and Heatmaps for Next.js (App Router and Pages Router)

Next.js mixes server rendering, static generation, and client-side navigation in one app. That's great for performance and SEO—and confusing for analytics. A page might be server-rendered on first load and then swapped client-side on every click after. Session replay captures what users actually saw, regardless of how it was rendered.

Table of Contents

1. Quick Summary
2. App Router Setup
3. Pages Router Setup
4. Client-Side Navigation
5. Identify Users After Login
6. Track Conversions
7. Privacy and Masking
8. Key Takeaways

Quick Summary

App Router Setup

In app/layout.tsx, add the loader using the next/script component with an async-friendly strategy so it loads after hydration without blocking rendering. The exact snippet, including the recommended strategy, is in Install in Next.js.

Because the root layout persists across navigations, the script loads once and stays alive for the whole session.

Pages Router Setup

In pages/_app.tsx, add the same next/script tag. _app wraps every page, so it also loads once per session.

Client-Side Navigation

Next.js Link navigations use the History API. DeepSync listens for history changes, so each route shows up as a page view in replays, heatmaps, and funnels. Dynamic routes like /product/[id] appear with their real URLs, which you can group when building heatmaps or funnels.

Identify Users After Login

Call identify once you know who the user is—typically in a client component that reads your session:

deepsync("identify", user.id, {
  email: user.email,
  plan: "pro",
});

Only send attributes you're comfortable teammates seeing. See the SDK API.

Track Conversions

For actions that don't have a unique URL—an upgrade, a file upload, a completed onboarding—track a custom event and use it as a goal:

deepsync("track", "onboarding_completed", { steps: 4 });

Privacy and Masking

• Inputs, passwords, and payment fields are masked in the browser by default.
• Add the ds-mask class to elements with sensitive text and ds-block to exclude elements entirely.
• If your project uses consent-required mode, call the consent function from your cookie banner. See consent modes.

Key Takeaways

• Add the loader once in the root layout or _app.
• Client-side navigations are tracked automatically.
• Identify users and track key events for searchable sessions and funnels.
• Replay doesn't care how HTML was rendered—only what users saw.

Conclusion

Next.js gives users a fast experience. Session replay shows you whether that experience actually works for them.

Start free · Install in Next.js