sdk-next.md

@telemetry-tracker/next

Next.js integration: provider, page tracking, and error boundary. Uses @telemetry-tracker/core under the hood; all events include anonymous device id and SDK version (see telemetry-core).

Install

In a monorepo workspace:

pnpm add @telemetry-tracker/next

Peer dependencies: next (≥14), react (≥18).

Setup

1. Wrap your app (or layout) with TelemetryProvider and pass your config.
2. Call useTrackPage(pathname) where you have access to the current pathname (e.g. in a layout or page) so route changes are sent as screen events.
3. Optionally wrap error-prone trees with TelemetryErrorBoundary so React errors are reported.

App Router example

app/layout.tsx (or a client layout):

"use client";

import { TelemetryProvider, useTrackPage } from "@telemetry-tracker/next";
import { usePathname } from "next/navigation";

const config = {
  ingestUrl: process.env.NEXT_PUBLIC_INGEST_URL || "http://localhost:3001",
  app: "my-next-app",
  environment: process.env.NODE_ENV,
  // webVitals: true by default — emits $web_vital events for LCP, INP, CLS, TTFB
};

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <TelemetryProvider config={config}>
      <TrackPage />
      {children}
    </TelemetryProvider>
  );
}

function TrackPage() {
  const pathname = usePathname();
  useTrackPage(pathname ?? "/");
  return null;
}

Error boundary

Wrap a section of the tree to report React errors and optionally show a fallback:

import { TelemetryErrorBoundary } from "@telemetry-tracker/next";

<TelemetryErrorBoundary fallback={<div>Something went wrong.</div>}>
  <MyComponent />
</TelemetryErrorBoundary>

If you don’t pass fallback, the boundary renders nothing when it catches an error.

API

Export	Description
init(config)	Call @telemetry-tracker/core’s init (usually done via TelemetryProvider).
identify(userId)	Set current user id.
trackEvent(name, properties?)	Send a named event (re-exported from core).
trackError(error, context?)	Report an error with optional context.
screen(name)	Record a screen/view (re-exported from core).
TelemetryProvider({ config, children })	Client component that calls init(config) on mount.
useTrackPage(pathname)	Sends screen(pathname) when pathname changes (client-only).
TelemetryErrorBoundary	Class component that reports errors in componentDidCatch and optionally renders a fallback.

Config shape is the same as telemetry-core (TelemetryNextConfig = TelemetryConfig).

Manual init and page tracking

If you prefer not to use the provider:

"use client";

import { init, useTrackPage } from "@telemetry-tracker/next";
import { usePathname } from "next/navigation";

init({ ingestUrl: "http://localhost:3001", app: "my-app", apiKey: process.env.NEXT_PUBLIC_TELEMETRY_API_KEY });

export function Navigation() {
  const pathname = usePathname();
  useTrackPage(pathname ?? "/");
  return <nav>...</nav>;
}

Ensure init runs only on the client (e.g. inside a "use client" component or useEffect).

Custom events and identify

Import trackEvent, screen, and identify from @telemetry-tracker/next:

import { trackEvent, identify } from "@telemetry-tracker/next";

trackEvent("signup_clicked", { source: "hero" });
identify(user.id);  // after login
identify(null);     // on logout