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

PageDescription
InitializationInstall, client provider, server setup, environment variables
CaptureTrack events from client (hooks) and server (API routes, Server Actions)
IdentifyIdentify users on client and server
Set person propertiesUpdate user properties with setPersonProperties, setPersonPropertiesOnce (client and server)
GroupAssociate users with groups (client and server)
Super propertiesRegister properties included with every event (client only)
AliasLink aliases to users (client and server)
Recording controlControl recording with startRecording, stopRecording, pauseRecording, resumeRecording, flush (client only)
Opt-outControl user opt-out with optOut, optIn, hasOptedOut (client only)
Flush and shutdownFlush queued events and graceful shutdown (server only)
Server trackingAPI routes, Server Actions, Pages Router, getServerSideProps
Page viewsAutomatic and manual page view tracking
ConfigurationSignalNextProvider and createSignalServer options

​
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.