Skip to content
Botscent

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

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.

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.

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

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.

5. Check the install

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

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.

Next steps