Next.js Bot Protection Integration

Next.js

On client side: Integrate BotBye client-side bot protection into a Next.js project using the botbye-nextjs package. 1. Install the package: npm i botbye-nextjs or yarn add botbye-nextjs 2. Add the <BotByeComponent> to your root layout (app/layout.tsx) or _app.tsx: import { BotByeComponent } from "botbye-nextjs" Place <BotByeComponent clientKey="00000000-0000-0000-0000-000000000000" /> inside the component tree (it renders nothing visible). This initializes the challenge runner on the client side. 3. In any "use client" component, generate a token before a protected request: import { runChallenge } from "botbye-nextjs" const token = await runChallenge() Call runChallenge() immediately before the fetch/axios call — do not cache the token. 4. Send the token to your Next.js API route in the x-botbye-token header: fetch("/api/login", { method: "POST", headers: { "x-botbye-token": token } }) 5. In the API route handler (server side), read the x-botbye-token header and validate it with validateRequest (see server-side setup). Full integration guide: https://botbye.com/docs/server-side/node-js/nextjs.md When the integration is complete, ask me for the clientKey and replace the placeholder in the appropriate places. on server side: Integrate BotBye server-side bot protection into an application using the botbye-nextjs package. 1. Install the package: npm i botbye-nextjs or yarn add botbye-nextjs 2. Initialize BotBye with server-key. The placement depends on where you run validation: - If validating in API route handlers: call init in instrumentation.ts (runs once at server startup): import { init } from "botbye-nextjs" init({ serverKey: "00000000-0000-0000-0000-000000000000" }) - If validating in middleware.ts: call init inside the middleware file itself. 3. Validate requests. Two patterns are supported: Pattern A — Middleware (protects multiple routes at once): In middleware.ts, import validateRequest from "botbye-nextjs". Extract the token: const token = request.headers.get("x-botbye-token") ?? "" Call: const botbyeResponse = await validateRequest({ request, token, customFields }) Check: if (!(botbyeResponse.result?.isAllowed ?? true)) return new NextResponse(null, { status: 403 }) Define the route matcher in the exported config Pattern B — Route handler (per-endpoint protection): In your route file (e.g., app/api/login/route.ts), import validateRequest. Extract token from the header, call validateRequest({ request, token }), check isAllowed. 4. The response object shape: { result: { isAllowed: boolean } | null, error: ... | null } Always use the null-safe fallback: botbyeResponse.result?.isAllowed ?? true (fail open if BotBye is unreachable). Full integration guide: https://botbye.com/docs/server-side/node-js/nextjs.md When the integration is complete, ask for the keys and replace the placeholder in the appropriate places.

Install

npm i botbye-nextjs

yarn add botbye-nextjs

Client Configuration

Init BotBye! using BotByeComponent


import { BotByeComponent } from "botbye-nextjs";

default function App() {
    /* Use your client-key */
    const clientKey = "00000000-0000-0000-0000-000000000000"

    return (
        <>
            <BotByeComponent clientKey={clientKey}/>

            ...
        </>
    );
}

Server Configuration

1. Init BotBye! with server-key

import { init } from "botbye-nextjs";

init({
    /* Use your server-key */
    serverKey: "00000000-0000-0000-0000-000000000000"
})

If validation runs in the handler, call init in instrumentation.ts. If it runs in middleware, call init inside middleware.ts.

Client Usage

1. To run challenge and generate BotBye! token call runChallenge. Send this token in any convenient way to the server. For example in x-botbye-token `typescript "use client" import { runChallenge } from "botbye-nextjs";

const LoginButton = () => { const onClick = async () => { const token = await runChallenge();

fetch("/api/login", { method: "POST", headers: { ["x-botbye-token"]: token } }) }

return (<button onClick={onClick}>{"Login"}</button>) } `

Server Usage

Add request validation

By middleware:

// middleware.ts

import { NextRequest, NextResponse } from "next/server";
import { validateRequest } from "botbye-nextjs";

async function middleware(request: NextRequest) {
    /* Get token from header or any place you store it */
    const token = request.headers.get("x-botbye-token") ?? "";

    /* Additional custom fields for linking request */
    const customFields = {
        someKey: "some-value"
    }

    const botbyeResponse = await validateRequest({
        request,
        token,
        customFields,
    })


    const isAllowed = botbyeResponse.result?.isAllowed ?? true;

    /* Decline request when it not pass validation */
    if (!isAllowed) {
        return new NextResponse(null, {status: 403, statusText: "Forbidden"})
    }

    return NextResponse.next();
}

/* Api endpoints middleware */
const config = {
    matcher: '/api/:path',
}

By handler

// app/api/login/route.ts

import { NextRequest, NextResponse } from 'next/server'
import { validateRequest } from "botbye-nextjs";

async function POST(request: NextRequest) {
    // Get token from header or any place you store it.
    // For example, from "x-botbye-token" header
    const token = request.headers.get("x-botbye-token") ?? "";

    const botbyeResponse = await validateRequest({
        request,
        token,
    })

    const isAllowed = botbyeResponse.result?.isAllowed ?? true;

    /* Decline request when it not pass validation */
    if (!isAllowed) {
        return new NextResponse(null, {status: 403, statusText: "Forbidden"})
    }

    return NextResponse.json({message: 'Login successful'})
}

Examples of BotBye API responses

Bot detected:

{
  "reqId": "f77b2abd-c5d7-44f0-be4f-174b04876583",
  "result": {
    "isAllowed": false
  },
  "error": "Automation tool used"
}

Bot not detected:

{
  "reqId": "f77b2abd-c5d7-44f0-be4f-174b04876583",
  "result": {
    "isAllowed": true
  },
  "error": null
}

Request banned by custom rule:

{
  "reqId": "f77b2abd-c5d7-44f0-be4f-174b04876583",
  "result": {
    "isAllowed": false
  },
  "error": {
    "message": "Banned by rule: MY_CUSTOM_RULE"
  }
}

Invalid server-key:

{
  "reqId": "f77b2abd-c5d7-44f0-be4f-174b04876583",
  "result": null,
  "error": {
    "message": "[BotBye] Bad Request: Invalid Server Key"
  }
}