Skip to content
Botscent

Netlify

Add the server half of Botscent to a Netlify site as an Edge Function and check the install.

Add the server half of Botscent to a Netlify site. The server half runs as a Netlify Edge Function, with the adapter from botscent/workers. It passes the request's own verdict to your function as a fourth argument. 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 site on Netlify
  • 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 netlify/edge-functions/botscent.ts. Wrap a function that continues to the site with withBotscent.

netlify/edge-functions/botscent.ts
import type { Context } from '@netlify/edge-functions'
import { withBotscent } from 'botscent/workers'

export default withBotscent<Context>((request, context) => context.next())

In netlify.toml, run the function on every path:

netlify.toml
[[edge_functions]]
  path = "/*"
  function = "botscent"

The edge function now inspects each request before Netlify serves the page.

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

To turn the transport off, pass { transport: 'never' } as the second argument of withBotscent. 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. Copy node_modules/botscent/dist/botscent.js into the publish directory, so that the site serves it at /botscent.js. If a frontend framework renders your pages, add the page half there instead. The Quickstart lists every framework.

4. Read the verdict

In the edge function, read the fourth argument.

netlify/edge-functions/botscent.ts
import type { Context } from '@netlify/edge-functions'
import { withBotscent } from 'botscent/workers'

export default withBotscent<Context>(async (request, context, _ctx, verdict) => {
  if (new URL(request.url).pathname === '/verdict') return Response.json(verdict)
  return context.next()
})

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 this verdict. Use no other field for access. See The trust model.

5. Check the install

Deploy the site. Then 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 a check fails, see Verify your install.

Next steps