Next.js — Initialization

Install the Next.js integration and set up both the client provider and the server SDK so you can track events from the browser and from API routes or Server Actions.

Installation

npm install @signal-js/nextjs

@signal-js/nextjs includes the browser SDK and the Node SDK. You do not need to install @signal-js/browser or @signal-js/node separately.

Client setup (App Router)

Create a client providers file and wrap your app with SignalNextProvider:

// app/providers.tsx
'use client';

import { SignalNextProvider } from '@signal-js/nextjs/client';

export function Providers({ children }) {
  return (
    <SignalNextProvider
      options={{
        apiKey: process.env.NEXT_PUBLIC_SIGNAL_API_KEY!,
        projectId: process.env.NEXT_PUBLIC_SIGNAL_PROJECT_ID!,
        // endpoint is optional (defaults to https://api.trysignal.ai/)
      }}
      trackPageViews
    >
      {children}
    </SignalNextProvider>
  );
}

Wrap the root layout with your providers:

// app/layout.tsx
import { Providers } from './providers';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Server setup (App Router)

Create a shared server client and a helper to read tracing headers from requests:

// lib/signal-server.ts
import { createSignalServer } from '@signal-js/nextjs/server';

export const signal = createSignalServer({
  apiKey: process.env.SIGNAL_API_KEY!,
  projectId: process.env.SIGNAL_PROJECT_ID!,
  // endpoint is optional (defaults to https://api.trysignal.ai/)
});

export function getSessionInfo(request: Request) {
  return {
    sessionId: request.headers.get('x-signal-session-id') || undefined,
    windowId: request.headers.get('x-signal-window-id') || undefined,
    distinctId: request.headers.get('x-signal-distinct-id') || undefined,
  };
}

Use signal and getSessionInfo in API routes, Server Actions, and (for Pages Router) in getServerSideProps and API route handlers.

Environment variables

Create .env.local:

NEXT_PUBLIC_SIGNAL_API_KEY=your-api-key
NEXT_PUBLIC_SIGNAL_PROJECT_ID=your-project-id

SIGNAL_API_KEY=your-api-key
SIGNAL_PROJECT_ID=your-project-id

Use NEXT_PUBLIC_ only for values needed in the browser. Keep server credentials without the prefix.

Next steps

Capture — Client and server event tracking
Server tracking — API routes, Server Actions, Pages Router
Configuration — Provider and server options

Getting Started

Features

Integrations

Initialization

Next.js — Initialization

Installation

Client setup (App Router)

Server setup (App Router)

Environment variables

Next steps

​Next.js — Initialization

​Installation

​Client setup (App Router)

​Server setup (App Router)

​Environment variables

​Next steps

Next.js — Initialization

Installation

Client setup (App Router)

Server setup (App Router)

Environment variables

Next steps