Documentation

Next.js

Use the @tacko/telemetry-next package for Next.js apps. It provides a provider, error boundary, and a hook to track page views. In the browser, uncaught errors and unhandled promise rejections are also reported automatically (via core’s global handlers after init()).

Install

pnpm add @tacko/telemetry-next
# or
npm install @tacko/telemetry-next

Setup

Wrap your app with TelemetryProvider and pass the config. Call useTrackPage(pathname) in your root layout so each route change sends a screen event.

// app/layout.tsx
import { TelemetryProvider, useTrackPage } from "@tacko/telemetry-next";

function TrackPageView({ pathname }: { pathname: string }) {
  useTrackPage(pathname);
  return null;
}

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <TelemetryProvider
          config={{
            ingestUrl: process.env.NEXT_PUBLIC_TELEMETRY_INGEST_URL ?? "",
            app: process.env.NEXT_PUBLIC_TELEMETRY_APP ?? "my-next-app",
          }}
        >
          <TrackPageView pathname={/* get pathname from usePathname() */} />
          {children}
        </TelemetryProvider>
      </body>
    </html>
  );
}

For the pathname you need a client component that uses usePathname() from next/navigation and passes it to useTrackPage(pathname).

Errors

After TelemetryProvider calls init(), uncaught sync errors and unhandled promise rejections in the browser are sent automatically. For React render errors, wrap parts of your tree with TelemetryErrorBoundary to report them (and optionally show a fallback).

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

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

Custom events and identify

Import trackEvent, screen, and identify from @tacko/telemetry-next when needed.

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

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