@smolcap/ai-tracker-nextjs

Track AI bot visits on your Next.js site with AI Tracker. The tracker runs in a fire-and-forget pattern inside Next.js proxy code: requests are not awaited and responses are never touched, so there is zero impact on page load times.

Setup

npm install @smolcap/ai-tracker-nextjs

Create or update proxy.ts in the root of your project (inside src/ if you use it; middleware.ts before Next.js 16):

import { withAiTracker } from "@smolcap/ai-tracker-nextjs";

export default withAiTracker({
  siteKey: process.env.AI_TRACKER_KEY!,
});

export const config = {
  matcher: [
    "/robots.txt",
    "/sitemap.xml",
    "/((?!api|_next/static|_next/image|favicon.ico).*)",
  ],
};

Set AI_TRACKER_KEY to your site key, then deploy as usual.

Custom proxy logic

Pass your existing proxy as the second argument. It is called with the same arguments and whatever it returns or throws reaches Next.js unchanged.

import { type AiTrackerConfig, withAiTracker } from "@smolcap/ai-tracker-nextjs";
import { NextResponse, type NextRequest } from "next/server";

const aiTrackerConfig: AiTrackerConfig = {
  siteKey: process.env.AI_TRACKER_KEY!,
  debug: process.env.NODE_ENV === "development",
};

export default withAiTracker(aiTrackerConfig, (request: NextRequest) => {
  const response = NextResponse.next();
  response.headers.set("x-custom-header", "value");
  return response;
});

Configuration

| Option | Type | | | --- | --- | --- | | siteKey | string | Your site key. Defaults to the AI_TRACKER_KEY environment variable. While empty, tracking is off. | | endpoint | string | Custom AI Tracker origin. Most sites can omit this. | | debug | boolean | Logs why a visit was not recorded. |

Behaviour

• Only GET/HEAD page requests whose user agent looks like a crawler are reported, in the background through event.waitUntil, with a 1.5 s timeout. Everything else returns immediately.
• A missing key or invalid endpoint turns tracking off with one warning; nothing ever throws.
• A site key only accepts visits for its own hostname; previews and other hostnames are rejected.
• The proxy runs before rendering, so status codes are not recorded. Visitor IPs are read only from headers set by Vercel (x-vercel-forwarded-for) or Cloudflare (cf-connecting-ip).
• Remove it by deleting the file (or unwrapping your proxy) and redeploying.