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

# Express

Add the server half of Botscent to an Express app and check the install.

Add the server half of Botscent to an Express app. The server half runs as Express middleware and puts the request's own verdict on `req.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:

* Express 4 or 5
* 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 server half

In `server.js`, add the Botscent middleware before your routes.

```js title="server.js"
const express = require('express')
const { botscent } = require('botscent/express')

const app = express()
app.use(botscent())

app.listen(3000)
```

Every handler after `app.use(botscent())` now gets the request's own verdict.

If your app uses ES modules, write `import { botscent } from 'botscent/express'`. The rest of the code stays the same.

By default, the middleware does not send the verdict to the page. Express runs at the origin, and an origin cannot see whether a CDN in front of it stores HTML. To turn the sending on, pass `{ transport: 'always' }` to `botscent`. For the details, see [From the server to the page](/docs/server-to-page).

> **Warning:** 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 Express 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 route handler, read `req.botscent`. In TypeScript, `req.botscent` has the type `Verdict | undefined` on Express's own `Request` type, when `@types/express` is installed.

```js title="server.js"
const express = require('express')
const { botscent } = require('botscent/express')

const app = express()
app.use(botscent())

app.get('/verdict', (req, res) => {
  res.json(req.botscent)
})

app.listen(3000)
```

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 `req.botscent`. Use no other field for access. See [The trust model](/docs/trust-model).

## 5. Check the install

Start the app. Then run the check against one of its pages.

```sh title="Terminal"
npx botscent check http://localhost:3000/
```

The `page-script` check prints `pass`, and the check exits with code 0. The `server-half` check prints `unknown`, because the transport is off at an origin. If a check fails, see [Verify your install](/docs/verify).

## Next steps

* [The verdict](/docs/verdict): what `type`, `agent_name` and `reasons` mean.
* [From the page to the server](/docs/page-to-server): send the page verdict to Express with a request.
* [Server API (TypeScript)](/docs/server-api): every option of the Express adapter and of `inspect`.
* [Express example](https://github.com/nalinbhardwaj/botscent/tree/main/examples/express): the tested Express app.