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

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

```sh title="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`.

```js title="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](/docs/server-to-page).

## 4. Read the verdict

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

```astro title="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`.

```ts title="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.

```astro title="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](/docs/trust-model) describes.

## 5. Check the install

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

```sh title="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](/docs/verify).

## Next steps

* [The verdict](/docs/verdict): Read what `type`, `agent_name` and `reasons` mean.
* [From the page to the server](/docs/page-to-server): Send the page verdict to an on-demand route with `reportHeaders`.
* [Server API (TypeScript)](/docs/server-api#inspect): Read what `inspect` reads from a request.
* [examples/astro](https://github.com/nalinbhardwaj/botscent/tree/main/examples/astro): Run an Astro site with both halves.