Next.js SDK

npm install @tell-rs/nextjs @tell-rs/browser

A drop-in client component for the App Router with automatic page view tracking.

@tell-rs/nextjs is a thin wrapper around the browser SDK. It adds a "use client" component that watches Next.js route changes and fires Page Viewed events automatically. You install @tell-rs/browser alongside because that’s where the actual tracking, sessions, and transport live.

Client components only. The Tell browser SDK runs in the browser and requires window, document, and localStorage. It cannot run in React Server Components. For server-side analytics (e.g. tracking API routes or server actions), use the Node.js SDK instead.

Setup

// app/layout.tsx
import { Tell } from "@tell-rs/nextjs";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Tell apiKey="YOUR_API_KEY" />
        {children}
      </body>
    </html>
  );
}

The Tell component watches usePathname() and useSearchParams() and fires a Page Viewed event on every route change. Disable with trackPageViews={false}.

With options

import { Tell } from "@tell-rs/nextjs";
import { redact, SENSITIVE_PARAMS } from "@tell-rs/browser";

<Tell
  apiKey="YOUR_API_KEY"
  options={{
    beforeSend: redact({ stripParams: SENSITIVE_PARAMS }),
    captureErrors: true,
  }}
/>

Manual tracking

"use client";
import { tell } from "@tell-rs/nextjs";

tell.track("Checkout Started", { items: 3 });
tell.identify("user_123", { plan: "pro" });

Server-side tracking

For API routes, middleware, or server actions, use @tell-rs/node separately:

// app/api/checkout/route.ts
import { Tell, production } from "@tell-rs/node";

const tell = new Tell(production("YOUR_API_KEY"));

export async function POST(req: Request) {
  const body = await req.json();
  tell.track(body.userId, "Checkout Completed", { total: body.total });
  return Response.json({ ok: true });
}

What you get from the browser SDK

All features documented in the browser SDK guide are available — sessions, device context, super properties, structured logging, opt-out, and beforeSend hooks. The Next.js package only adds the auto page view component.

Getting Started

Tracking

Pipeline

Analytics

Installing

Next.js SDK

Setup

With options

Manual tracking

Server-side tracking

What you get from the browser SDK

​Setup

​With options

​Manual tracking

​Server-side tracking

​What you get from the browser SDK

Setup

With options

Manual tracking

Server-side tracking

What you get from the browser SDK