Skip to content
Botscent

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, React, 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.

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.

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.

  • 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 lists every framework.

4. Read the verdict

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

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.

5. Check the install

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

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.

Next steps