Next.js — Configuration

Configure the client provider (SignalNextProvider) and the server client (createSignalServer). Client options are the same browser SDK options as in the React configuration.

SignalNextProvider (client)

Prop	Type	Default	Description
`options`	`SignalOptions`	required	Browser SDK config. Required: `apiKey`, `projectId`. Optional: `endpoint` (defaults to `https://api.trysignal.ai/`). See React configuration for full options.
`trackPageViews`	`boolean`	`true`	Automatically track `$pageview` on route changes
`trackSearchParams`	`boolean`	`false`	Include URL search params in page view events (requires Suspense boundary)
`autoStart`	`boolean`	`true`	Start recording when the provider mounts

createSignalServer (server)

Option	Type	Default	Description
`endpoint`	`string`	`https://api.trysignal.ai/`	API endpoint for sending events
`apiKey`	`string`	required	API key for authentication
`projectId`	`string`	`'default'`	Project ID
`disabled`	`boolean`	`false`	When `true`, returns a no-op client
`debug`	`boolean`	`false`	Enable debug logging
`flushBatchSize`	`number`	`20`	Flush when this many events are queued
`flushInterval`	`number`	`10000`	Flush interval in ms
`timeout`	`number`	`30000`	Request timeout in ms
`compression`	`boolean`	`true`	Enable gzip compression
`fetch`	`typeof fetch`	`globalThis.fetch`	Custom fetch implementation

You must call createSignalServer() once (e.g. in lib/signal-server.ts) before using the server helpers below. The helpers use the same singleton client.

Server helpers

These utilities are exported from @signal-js/nextjs/server. They work with the client created by createSignalServer().

trackServerEvent(options)

Fire a single event from an API route or Server Action without importing your shared signal client. Uses the singleton from createSignalServer; call createSignalServer() at least once (e.g. in lib/signal-server.ts) before using.

Option	Type	Required	Description
`distinctId`	`string`	yes	User identifier
`event`	`string`	yes	Event name
`properties`	`Record<string, unknown>`	no	Event properties

When to use: One-off event tracking in API routes or Server Actions when you don’t need to pass sessionId/windowId for correlation. For session correlation, use your shared signal client and getSessionInfo instead.

// app/api/checkout/route.ts or pages/api/checkout.ts
import { trackServerEvent } from '@signal-js/nextjs/server';

export async function POST(request: Request) {
  const body = await request.json();
  // ... process checkout ...

  await trackServerEvent({
    distinctId: body.userId,
    event: 'checkout_completed',
    properties: { amount: body.amount, orderId: body.orderId },
  });

  return Response.json({ success: true });
}

getSignalServerSideProps(getServerSidePropsFunc, options?)

Wrap your Pages Router getServerSideProps to inject Signal-related props (distinctId, sessionId) into the page. Your wrapper runs first; then Signal props are merged into the returned props.

Option	Type	Description
`getDistinctId`	`(context) => string \| undefined`	Return the user’s distinct ID from the request (e.g. from cookies or session).
`getSessionId`	`(context) => string \| undefined`	Optional. Return the session ID (e.g. from headers) for correlation.

When to use: Pages Router when you want Signal context (e.g. distinctId, sessionId) available as page props for client components or for tracking.

// pages/dashboard.tsx
import { getSignalServerSideProps } from '@signal-js/nextjs/server';

export const getServerSideProps = getSignalServerSideProps(
  async (context) => {
    // Your existing data fetching
    const data = await fetchDashboardData(context.req);
    return { props: { data } };
  },
  {
    getDistinctId: (context) => context.req.cookies.userId,
    getSessionId: (context) => context.req.headers['x-signal-session-id'] as string | undefined,
  }
);

export default function Dashboard({ data, distinctId, sessionId }) {
  // distinctId and sessionId are now available
  return <div>...</div>;
}

withSignalConfig(signalConfig)

Wrap your Next.js config to inject Signal env vars for the client: NEXT_PUBLIC_SIGNAL_ENDPOINT and NEXT_PUBLIC_SIGNAL_PROJECT_ID. This is an alternative to setting them in .env.local.

Option	Type	Description
`endpoint`	`string`	Optional. API endpoint (set as `NEXT_PUBLIC_SIGNAL_ENDPOINT`). Defaults to `https://api.trysignal.ai/`.
`apiKey`	`string`	API key (not exposed to client by this helper)
`projectId`	`string`	Optional. Project ID (set as `NEXT_PUBLIC_SIGNAL_PROJECT_ID`)
`disableSourceMaps`	`boolean`	Optional. Disable source maps upload

When to use: When you prefer to configure Signal in next.config.js instead of (or in addition to) .env.local.

// next.config.js
const { withSignalConfig } = require('@signal-js/nextjs/server');

module.exports = withSignalConfig({
  endpoint: process.env.SIGNAL_ENDPOINT,
  apiKey: process.env.SIGNAL_API_KEY,
  projectId: process.env.SIGNAL_PROJECT_ID,
})({
  // your existing Next.js config
  reactStrictMode: true,
});

The client will receive process.env.NEXT_PUBLIC_SIGNAL_ENDPOINT and process.env.NEXT_PUBLIC_SIGNAL_PROJECT_ID at build time. Keep apiKey and other secrets in server-only env (e.g. SIGNAL_API_KEY in .env.local).

Browser options (options prop)

Client options are the same browser SDK options as in React — Configuration. That page includes:

Transport and batching — compression, flushInterval, maxBatchSize, getSignedUploadUrl
Features — enableSessionReplay, enableNetworkCapture, enableConsoleCapture, enableSessionTracking, enablePerformanceTracking, enableBrowserDetection, debug
sessionRecordingMasking — How masking works: blockClass/blockSelector (hide elements), maskTextClass/maskTextSelector (replace text with ***), ignoreClass (don’t record input values), maskAllInputs vs maskInputOptions (per-type input masking), maskTextFn/maskInputFn (custom transforms). With examples and JSX usage.
networkCaptureOptions — How network capture works: recordHeaders/recordBody (what is captured), sensitiveHeaders (redact header values), urlDenyList (exclude URLs), payloadSizeLimitBytes (truncate large bodies), maskRequestFn (custom redaction or drop). With examples.
consoleCaptureOptions — levels, captureErrors, captureUnhandledRejections, stringLengthLimit, maskSensitiveData
Session and advanced — sessionId, sessionIdleTimeoutSeconds, maxSessionLengthSeconds, addTracingHeaders (for server correlation), rrwebConfig, requiredBrowserFeatures, debugPersistToLocalStorage, debugLocalStorageKey

Getting Started

Features

Integrations

Configuration

Next.js — Configuration

SignalNextProvider (client)

createSignalServer (server)

Server helpers

trackServerEvent(options)

getSignalServerSideProps(getServerSidePropsFunc, options?)

withSignalConfig(signalConfig)

Browser options (options prop)

See also

​Next.js — Configuration

​SignalNextProvider (client)

​createSignalServer (server)

​Server helpers

​trackServerEvent(options)

​getSignalServerSideProps(getServerSidePropsFunc, options?)

​withSignalConfig(signalConfig)

​Browser options (options prop)

​See also

Next.js — Configuration

SignalNextProvider (client)

createSignalServer (server)

Server helpers

trackServerEvent(options)

getSignalServerSideProps(getServerSidePropsFunc, options?)

withSignalConfig(signalConfig)

Browser options (options prop)

See also