Skip to main content

​
Next.js Integration

Use Signal JS with Next.js using the @signal-js/nextjs package. It provides client components (SignalNextProvider, hooks) and server utilities (createSignalServer). You add a getSessionInfo() helper in lib/signal-server.ts (see Initialization) to read tracing headers for session correlation.

​
Quick start

  1. Install — npm install @signal-js/nextjs
  2. Client — Wrap your app with SignalNextProvider in a client providers file and add it to your root layout. See Initialization.
  3. Server — Create a shared signal client with createSignalServer and a getSessionInfo() helper in lib/signal-server.ts. See Initialization.
  4. Track events — Use hooks on the client and signal.capture() on the server with session identifiers. See Capture and Server tracking.

​
Sub-pages

​
Features

  • App Router support — Full support for Next.js 13+ App Router
  • Pages Router support — Compatible with Pages Router
  • Server-side tracking — Track events from API routes and server actions
  • Session correlation — Link client and server events using tracing headers
  • Page view tracking — Automatic page view tracking on route changes

​
Best practices

  1. Use environment variables — Store credentials in .env.local.
  2. Use addTracingHeaders only when needed — Set in options only if you track server-side events and want correlation.
  3. Track server events — Pass sessionId and windowId from request headers to signal.capture() so events link to the same session replay.
  4. Separate client/server configs — Use NEXT_PUBLIC_ prefix for client-side variables.
  5. Use sessionRecordingMasking — Add signal-no-capture, signal-mask, or signal-ignore-input classes to sensitive UI.