> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aranx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Next.js

> Track AI bot visits and visitors from AI apps on a Next.js site

The `@aranx/ai-analytics` package runs in the Next.js proxy. It records
requests from AI bots such as `ChatGPT-User` and `PerplexityBot`, and visits
from people who open your site from a link in an AI app. It sends nothing for
other traffic.

## Before you start

* In Aranx, open **AI Visibility** for the website and create a server
  key. Aranx shows the key once.
* Next.js 13 or later. Next.js 16 calls the file `proxy.ts`. Earlier versions
  call it `middleware.ts`.

## Setup

**1. Install the package**

```sh theme={null}
npm install @aranx/ai-analytics
```

**2. Set the key**

Add the key to `.env.local` for local development:

```sh .env.local theme={null}
ARANX_TRAFFIC_KEY=arx_tk_...
```

Add the same variable to your host, for example in **Vercel > Project >
Settings > Environment Variables**. Do not commit the key, and do not
prefix it with `NEXT_PUBLIC_`.

**3. Add the proxy**

Create `proxy.ts` next to the `app` directory (in `src/` if your project
uses it):

```ts proxy.ts theme={null}
import { withAiTraffic } from '@aranx/ai-analytics/next';

export const proxy = withAiTraffic();

// Skip static files.
export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)']
};
```

Before Next.js 16, name the file `middleware.ts` and the export
`middleware`.

**4. Deploy**

Deploy the site. Aranx shows the first bot visits on the AI visibility
page.

## Client IP

Aranx counts a bot visit only when its IP is in the bot's published IP ranges,
so the proxy must know the client IP. On Vercel it reads `X-Real-IP`, which
Vercel sets, and you have nothing to do. On another host (OpenNext on
Cloudflare, Netlify, your own server) behind a proxy that is the only way to
reach the server, name the one header that proxy sets:

```ts proxy.ts theme={null}
export const proxy = withAiTraffic(undefined, {
  clientIpHeader: 'cf-connecting-ip'
});
```

Name only a header your proxy overwrites. A client can send any header
itself. For `x-forwarded-for` the package takes the last address, the one
your proxy appended.

## Keep an existing proxy

Pass your proxy to `withAiTraffic`. It records the request, then runs your
proxy and returns its response.

```ts proxy.ts theme={null}
import { NextResponse, type NextRequest } from 'next/server';
import { withAiTraffic } from '@aranx/ai-analytics/next';

export const proxy = withAiTraffic(async (request: NextRequest) => {
  // Your existing proxy
  return NextResponse.next();
});
```

The proxy records only the requests its `matcher` covers, so the matcher must
cover every public page. If your existing proxy must run only on some paths,
such as `/dashboard`, widen the matcher and call your proxy only for those
paths:

```ts proxy.ts theme={null}
import { NextResponse, type NextRequest } from 'next/server';
import { withAiTraffic } from '@aranx/ai-analytics/next';

async function dashboardProxy(request: NextRequest) {
  // Your existing proxy
  return NextResponse.next();
}

export const proxy = withAiTraffic(async (request: NextRequest) => {
  if (request.nextUrl.pathname.startsWith('/dashboard')) {
    return dashboardProxy(request);
  }
  return NextResponse.next();
});

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)']
};
```

## Check the setup

Send a request with an AI user agent:

```sh theme={null}
curl -A "Mozilla/5.0 (compatible; ChatGPT-User/1.0)" https://example.com/
```

Aranx does not count this visit. It counts a bot visit only from an IP in the
ranges that OpenAI, Anthropic, and Perplexity publish for their bots, and
scanners often fake these user agents. The request still marks the key as
used.

In Aranx, **Settings > Sources** on the AI visibility page shows when the key
was last used.

## What the package sends

For each AI request: the page URL without its query (it keeps `utm_source`),
the user agent, and the time. Bot visits also carry the client IP, which Aranx checks against the bot's published IP ranges and does not store. The proxy
runs before the page, so events have no response status. Tracking never
throws and never delays the response.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.