> For an index of all Botscent documentation, see https://botscent.nibnalin.me/llms.txt.

# Hono

Add the server half of Botscent to a Hono app and check the install.

Add the server half of Botscent to a Hono app. The server half runs as Hono middleware and gives each handler the request's own verdict through `c.get('botscent')`. For the page half, see [A script tag](/docs/script-tag), [React](/docs/react), [Vue](/docs/vue) or the page for the framework your site uses.

## Before you start

You need:

* Hono 4
* Node.js 22.12 or later, to install the package

## 1. Install the package

Install `botscent` from npm.

```sh title="Terminal"
npm install botscent
```

With pnpm, yarn or bun, use their `add` command.

## 2. Add the server half

In `src/index.ts`, add the Botscent middleware with `use`. Chain the call to `new Hono()`, so that `c.get('botscent')` has a type.

```ts title="src/index.ts"
import { Hono } from 'hono'
import { botscent } from 'botscent/hono'

const app = new Hono().use(botscent())

export default app
```

Every handler on `app` now gets the request's own verdict.

The `transport` option controls whether the middleware sends the verdict to the page. The default depends on where Hono runs. For the details, see [From the server to the page](/docs/server-to-page).

* **On Cloudflare Workers**, the transport is on by default. A Worker runs per request in front of the cache. The middleware also reads Cloudflare's `request.cf`, so the platform's verified-bot field counts as evidence.
* **On any other runtime, such as Node.js**, the transport is off by default. An origin cannot see whether a CDN in front of it stores HTML.

If your Worker stores HTML with the Cache API, pass `{ transport: 'never' }` to `botscent`.

> **Warning:** Outside Cloudflare Workers, do not set `transport: 'always'` unless no shared cache stores your HTML. If a cache stores an agent's page and ignores `Cache-Control: no-store`, a person can get the agent's `Server-Timing` entry. If you are not sure, keep the default.

## 3. Add the page half

The server half reads only what each request declares. The page half finds agents that operate a browser, from inside the page.

If Hono sends your HTML, add `<script defer src="/botscent.js"></script>` to each page. Serve `node_modules/botscent/dist/botscent.js` at `/botscent.js` from your own origin. If a frontend framework renders your pages, add the page half there instead. The [Quickstart](/docs/quickstart) lists every framework.

## 4. Read the verdict

In a handler, call `c.get('botscent')`.

```ts title="src/index.ts"
import { Hono } from 'hono'
import { botscent } from 'botscent/hono'

const app = new Hono().use(botscent())

app.get('/verdict', (c) => c.json(c.get('botscent')))

export default app
```

A request from `curl` to `/verdict` gets `{"type":"agent","agent_name":"curl","reasons":["ua.declared-agent-token"]}`.

To give an agent access, use `isVerified` from `botscent/server` on this verdict. Use no other field for access. See [The trust model](/docs/trust-model).

## 5. Check the install

Deploy or start the app. Then run the check against one of its pages.

```sh title="Terminal"
npx botscent check https://your-site.example/
```

On Cloudflare Workers, the `server-half` and `page-script` checks print `pass`, and the check exits with code 0. On Node.js, `server-half` prints `unknown`, because the transport is off. If a check fails, see [Verify your install](/docs/verify).

## Next steps

* [The verdict](/docs/verdict): what `type`, `agent_name` and `reasons` mean.
* [Cloudflare Workers](/docs/cloudflare-workers): add the server half to a Worker without Hono.
* [Server API (TypeScript)](/docs/server-api): every option of the Hono adapter and of `inspect`.
* [Hono example](https://github.com/nalinbhardwaj/botscent/tree/main/examples/hono): the tested Hono app on Cloudflare Workers.