Skip to main content
Use the @siteline/nextjs package to track AI bot visits on your Next.js site. The tracker runs in a fire-and-forget pattern inside Next.js proxy code — requests are not awaited, so there is zero impact on page load times.

​
Prerequisites

​
Setup

1

Install the package

npm install @siteline/nextjs
2

Add the proxy

Create or update your proxy.ts file in the root of your project:
proxy.ts
import { withSiteline } from "@siteline/nextjs";

export default withSiteline({
  websiteKey: process.env.SITELINE_WEBSITE_KEY!,
});

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

Deploy

Deploy your application as usual. The proxy will begin tracking AI bot visits immediately.

​
How it works

The package hooks into Next.js proxy, which runs on every matched request before the page renders:
  1. A visitor (or AI bot) makes a request to your Next.js site
  2. The proxy extracts bot-relevant metadata (URL, user agent, IP, referrer)
  3. Tracking data is sent to Siteline asynchronously — the request is not awaited
  4. The page response is returned to the visitor unmodified
Static assets (_next/static, _next/image, favicon.ico) are excluded via the route matcher.

​
Custom Proxy Logic

If you already have proxy logic, pass it as the second argument to withSiteline:
proxy.ts
import { type SitelineConfig, withSiteline } from '@siteline/nextjs';
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

const sitelineConfig: SitelineConfig = {
  websiteKey: process.env.SITELINE_WEBSITE_KEY!,
  debug: process.env.NODE_ENV === 'development',
};

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

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

​
Configuration

​
websiteKey
string
required
Your Siteline website key. Found under Agent Analytics > Manage Configuration in your Siteline workspace. You can pass it directly or set it with the SITELINE_WEBSITE_KEY environment variable.
​
endpoint
string
Custom Siteline intake endpoint. Most sites can omit this.
​
debug
boolean
Enables debug logging. Use this only while developing or troubleshooting.
​
matcher
string[]
Next.js route matcher config. The example pattern excludes API routes and static assets. Adjust to match the routes you want to track.

​
Troubleshooting

Ensure proxy.ts is in the root of your project (next to package.json), not inside src/ or app/. Next.js picks up proxy files from the project root.
Navigate to Agent Analytics in your Siteline workspace and click Manage Configuration to view or regenerate your key.
No. Pass your existing logic as the second argument to withSiteline. It runs asynchronously and returns your response unchanged.
No. The tracking call is fire-and-forget — it is not awaited and never blocks the response. All errors are silently caught.
Need help? Book a setup call and we’ll walk you through it.