@punchline-analytics/next
v0.6.1
Published
See which visitors are AI agents: Next.js middleware/proxy for Punchline Analytics. Forwards a minimal, privacy-reduced event per page request.
Maintainers
Readme
@punchline-analytics/next
Shows how much of your site's traffic is AI agents, and which ones. This package runs in your Next.js proxy (or middleware), and for each page request it sends a small event to your Punchline Analytics collector, after the response has gone out.
- No cookies, no browser script, nothing added to your pages.
- Doesn't slow pages down. The event is sent after the response; our code adds about 1 ms.
- Never breaks your site. If Punchline is misconfigured or unreachable, requests continue normally.
Install
npm install @punchline-analytics/nextSet one environment variable (your Punchline Analytics dashboard gives you the value):
PUNCHLINE_DSN=https://<site-id>:<secret>@<your-collector>/api/collectNext.js 16: create proxy.ts at the project root, or in src/ if you use one:
import { punchline } from "@punchline-analytics/next";
export const proxy = punchline();
export const config = {
matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};Next.js 15, or to run on the edge runtime: use middleware.ts with export const middleware = punchline(); and the same config.
Next.js reads matcher at build time, so it has to be written out in your file as shown.
Already have a proxy or middleware?
Call the tracker inside it:
import { createTracker } from "@punchline-analytics/next";
import { NextResponse, type NextFetchEvent, type NextRequest } from "next/server";
const tracker = createTracker();
export function proxy(request: NextRequest, event: NextFetchEvent) {
tracker.track(request, event);
// …your existing logic…
return NextResponse.next();
}What gets sent
For each page view (GET/HEAD for pages, plus .txt, .md and .xml files such as robots.txt and llms.txt), the package sends one event, server to server:
- The host, the path and
utm_*values. Every other query parameter, and the#fragment, are removed before sending. - The referrer's host only.
- The
Acceptheader, cut to 200 characters. - Whether the browser sent
Sec-GPC: 1. - The country code your host provides (
x-vercel-ip-countryon Vercel). - Web Bot Auth signature headers, when an agent sends them.
- The visitor's IP address and user agent. The collector uses these in memory to classify the request and to compute a daily visitor hash, then discards them; they're never stored or logged.
Not tracked: images, scripts, styles, other assets, or Next.js link prefetches.
Options
punchline({
dsn: "...", // default: process.env.PUNCHLINE_DSN
timeoutMs: 3000, // give up sending after this long
serverTiming: true, // add `Server-Timing: punchline;dur=…` (default: PUNCHLINE_SERVER_TIMING=1)
onError: (err) => {}, // configuration or network errors (default: ignored)
});Troubleshooting
- No events arriving. Check
PUNCHLINE_DSNis set for the environment you deployed. PassonError: console.erroronce to see why sends are failing. - Measuring the overhead. Set
PUNCHLINE_SERVER_TIMING=1and look at theServer-Timingresponse header.
