Skip to content
Botscent

Vercel

Add the server half of Botscent to a Vercel project as Routing Middleware and check the install.

Add the server half of Botscent to a Vercel project that does not use Next.js. The server half runs as Vercel Routing Middleware in middleware.ts. For a Next.js app, see Next.js. For the page half, see A script tag, React, Vue or the page for the framework your site uses.

Before you start

You need:

  • A Vercel project that does not use Next.js
  • 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

Create middleware.ts in the project root. Export the Botscent middleware as the default export.

middleware.ts
export { default } from 'botscent/vercel'

The middleware now inspects each request and then continues to your site.

If middleware.ts already exists, wrap your middleware with withBotscent:

middleware.ts
import { withBotscent } from 'botscent/vercel'

function middleware(request: Request) {
  if (new URL(request.url).pathname === '/old') return Response.redirect(new URL('/new', request.url))
}

export default withBotscent(middleware)

Your middleware still runs first, before Botscent inspects the request.

Routing Middleware runs per request in front of Vercel's cache, so the transport is on by default. For an agent's document navigation, the middleware adds a Server-Timing entry with Cache-Control: no-store. The page half reads the entry.

To turn the transport off, write withBotscent({ transport: 'never' }), or pass the options after your middleware. For the details, see From the server to the page.

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 your site is plain 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

The middleware does not pass the verdict to your code. It sends the verdict to the page instead.

On an agent's document navigation, the page half reads the Server-Timing entry. The page verdict then includes the reasons of the request's own verdict. Read the page verdict in the page, for example with verdict from window.botscent.

In a Vercel Function, call inspect from botscent/server to get the request's own verdict:

api/verdict.ts
import { inspect } from 'botscent/server'

export async function GET(request: Request) {
  const verdict = await inspect(request)
  return Response.json(verdict)
}

A request from curl to /api/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 the project. Then, in the project's directory, run the check against one of its pages.

Terminal
npx botscent check https://your-site.example/

The server-half and page-script checks print pass, and the check exits with code 0. If you replaced an existing middleware instead of wrapping it, the adapters check prints fail. If a check fails, see Verify your install.

Next steps