> ## 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.

# Hono

> Track AI bot visits and visitors from AI apps on a Hono app

The `@aranx/ai-analytics` package adds a Hono middleware. 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 works on Cloudflare
Workers, Node.js, Bun, and Deno.

## Before you start

* In Aranx, open **AI Visibility** for the website and create a server
  key. Aranx shows the key once.

## Setup

**1. Install the package**

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

**2. Set the key**

On Cloudflare Workers, add it as a secret:

```sh theme={null}
npx wrangler secret put ARANX_TRAFFIC_KEY
```

On Node.js, Bun, or Deno, set the `ARANX_TRAFFIC_KEY` environment
variable on the server. Do not commit the key. If you keep the key in
`.env`, the server must load the file before it creates the middleware.
On Node.js, use `node --env-file=.env server.js` (Node.js 20.6 or later)
or the dotenv loader of the project. On Deno, use
`deno run --env-file=.env main.ts`. Bun loads `.env` by itself.

**3. Add the middleware**

Register it before your routes:

```ts src/index.ts theme={null}
import { Hono } from 'hono';
import { aiTraffic } from '@aranx/ai-analytics/hono';

const app = new Hono();

app.use(aiTraffic());

// Your routes
```

On Workers, the middleware reads the key from the `ARANX_TRAFFIC_KEY`
binding. Elsewhere it reads `process.env`.

Aranx counts a bot visit only when its IP is in the bot's published IP
ranges. On Workers the client IP comes from `CF-Connecting-IP`. On
Node.js, Bun, and Deno it comes from the connection. Behind a proxy
that is the only way to reach the server, name the one header it sets,
for example `aiTraffic({ clientIpHeader: 'x-real-ip' })`.

**4. Deploy**

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

## 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, the response status, and the time. Bot visits also carry the
client IP, which Aranx checks against the bot's published IP ranges and does
not store. Tracking never throws and never delays the response.


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