Skip to content
Botscent

Astro

Add both halves of Botscent to an Astro site with one integration and check the install.

Add Botscent to an Astro site. One integration adds both halves. The page half runs on every page, and the server half runs on routes rendered on demand.

Before you start

You need:

  • Astro 4 to 7.
  • Node.js 22.12 or later.

1. Install the package

Install botscent from npm.

Terminal
npm install botscent

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

2. Add the page half

In astro.config.mjs, add the botscent integration from botscent/astro to integrations.

astro.config.mjs
import { defineConfig } from 'astro/config'
import botscent from 'botscent/astro'

export default defineConfig({
  integrations: [botscent()],
})

Every page now loads the page half.

3. Add the server half

The integration from step 2 also adds the server half as Astro middleware. You add no other code.

The middleware runs on routes rendered on demand. To render a route on demand, the project needs an Astro server adapter, such as @astrojs/node. A prerendered page has no visitor's request, so the server half does not run for a prerendered page.

The integration does not send the request's own verdict to the page, because the transport is off by default. See From the server to the page.

4. Read the verdict

On a route rendered on demand, read the request's own verdict from Astro.locals.botscent.

src/pages/account.astro
---
const verdict = Astro.locals.botscent
---
<html lang="en">
  <body>
    <pre>{JSON.stringify(verdict)}</pre>
  </body>
</html>

The page now shows the request's own verdict.

For TypeScript, declare the type of Astro.locals.botscent in src/env.d.ts.

src/env.d.ts
declare namespace App {
  interface Locals {
    botscent: import('botscent').Verdict
  }
}

To read the page verdict, call verdict and subscribe from botscent in a client script.

src/components/Verdict.astro
<pre id="verdict"></pre>
<script>
  import { subscribe, verdict } from 'botscent'
  const show = () => (document.getElementById('verdict')!.textContent = JSON.stringify(verdict()))
  show()
  subscribe(show)
</script>

In a normal browser, the component shows {"type":"human","reasons":[]}.

Warning: Do not use agent_name or the page verdict to allow access. Anyone can send the headers that produce a name, and the browser computes the page verdict. Use isVerified on the request's own verdict, as The trust model describes.

5. Check the install

Start the dev server. Then run the check against its URL.

Terminal
npx botscent check http://localhost:4321/

The page-script check prints pass, and the command exits with code 0.

The server-half check prints unknown, because the transport is off by default. If a check fails, see Verify your install.

Next steps