Skip to main content

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

PropTypeDefaultDescription
optionsSignalOptionsrequiredBrowser SDK config. Required: apiKey, projectId. Optional: endpoint (defaults to https://api.trysignal.ai/). See React configuration for full options.
trackPageViewsbooleantrueAutomatically track $pageview on route changes
trackSearchParamsbooleanfalseInclude URL search params in page view events (requires Suspense boundary)
autoStartbooleantrueStart recording when the provider mounts

​
createSignalServer (server)

OptionTypeDefaultDescription
endpointstringhttps://api.trysignal.ai/API endpoint for sending events
apiKeystringrequiredAPI key for authentication
projectIdstring'default'Project ID
disabledbooleanfalseWhen true, returns a no-op client
debugbooleanfalseEnable debug logging
flushBatchSizenumber20Flush when this many events are queued
flushIntervalnumber10000Flush interval in ms
timeoutnumber30000Request timeout in ms
compressionbooleantrueEnable gzip compression
fetchtypeof fetchglobalThis.fetchCustom 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.
OptionTypeRequiredDescription
distinctIdstringyesUser identifier
eventstringyesEvent name
propertiesRecord<string, unknown>noEvent 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.
OptionTypeDescription
getDistinctId(context) => string | undefinedReturn the user’s distinct ID from the request (e.g. from cookies or session).
getSessionId(context) => string | undefinedOptional. 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.
OptionTypeDescription
endpointstringOptional. API endpoint (set as NEXT_PUBLIC_SIGNAL_ENDPOINT). Defaults to https://api.trysignal.ai/.
apiKeystringAPI key (not exposed to client by this helper)
projectIdstringOptional. Project ID (set as NEXT_PUBLIC_SIGNAL_PROJECT_ID)
disableSourceMapsbooleanOptional. 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

​
See also