Chokhdocs
GitHub

Next.js

Chokh in an App Router app, first-party: the tracker served from your own domain, its events posted to your own domain and forwarded with each visitor's real address.

@chokh/next works with Next 15 or 16, React 18.2 or newer, and Node 22 or newer. It is not on npm yet: it is published with Chokh's first release.

npm install @chokh/next

1. The config

next.config.mjs serves the tracker and its two companions under /_pa, from your own origin, where filter lists do not reach.

import { withChokh } from '@chokh/next/config';

/** @type {import('next').NextConfig} */
const nextConfig = {};

// Serves a.js, v.js and e.js under /_pa, from your own origin.
export default withChokh(nextConfig, { url: process.env.NEXT_PUBLIC_CHOKH_URL });

2. The collect route

app/%5Fpa/collect/route.ts is the address the tracker posts to, /_pa/collect. It forwards each batch to your Chokh with the visitor's address, signed so the collector believes it.

import { createCollectRoute } from '@chokh/next/collect';

// /_pa/collect: forwards the tracker's batches to Chokh with the visitor's
// address, signed with CHOKH_PROXY_SECRET.
export const POST = createCollectRoute({
  url: process.env.NEXT_PUBLIC_CHOKH_URL,
  proxySecret: process.env.CHOKH_PROXY_SECRET,
});

The folder is %5Fpa and not _pa: the App Router never routes a folder whose name starts with an underscore, and %5F is how a segment that really starts with one is written.

Set the same CHOKH_PROXY_SECRET on your Chokh server, with REAL_IP_HEADER=X-Chokh-Forwarded-For (see the environment). The secret stays on servers: it is never a NEXT_PUBLIC_ variable.

Read this before you deploy. The route signs the address it reads, so it must read a header your host sets itself and never one a visitor can send. By default it reads the first entry of x-forwarded-for, which is right on Vercel, which documents that it overwrites that header. Anywhere else, say where the address is with clientAddress; the package's README has a table of hosts and what to pass for each.

3. The tag

import type { ReactNode } from 'react';
import { Analytics } from '@chokh/next';

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Analytics site="my_site" vitals errors />
      </body>
    </html>
  );
}

Events

useTrack, useChokh and the plain track, identify and reset come from the same package.

'use client';

import { useTrack } from '@chokh/next';

export function SignupButton() {
  const track = useTrack();
  return <button onClick={() => track('signup', { plan: 'pro' })}>Sign up</button>;
}

What <Analytics /> takes

Prop What it does
site The site's id. Required.
path The first-party path, /_pa by default.
visitorId 'persistent' keeps an id in the browser; 'cookieless', the default, stores nothing.
vitals, errors Load the scripts for Core Web Vitals and JavaScript errors.
consent Nothing is sent until it is true; a later false withdraws.
hashRouting, respectDnt Count a change of #hash as a page; honour Do Not Track.
nonce A Content-Security-Policy nonce for every script it adds.

Edit this page on GitHub

Chokhdocs

Chokh on GitHub