@adwait12345/telemetry-next

Next.js middleware adapter for the Telemetry SDK. Detects bots and crawlers on every server-side request and sends tracking payloads to the Telemetry API — without slowing down your users.

Requirements

• Next.js 13.0.0 or later (App Router or Pages Router)
• A Telemetry account with a Project ID and Server Secret

Installation

npm install @adwait12345/telemetry-next @adwait12345/telemetry-core
# or
pnpm add @adwait12345/telemetry-next @adwait12345/telemetry-core

Setup

1. Create middleware.ts at the root of your project

// middleware.ts  (next to your app/ or pages/ folder)
import { telemetryMiddleware } from "@adwait12345/telemetry-next";
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

const telemetry = telemetryMiddleware({
  projectId: "your-project-id",
  apiUrl: "https://telemetry-uqd3.onrender.com",
  serverSecret: "sk_...",
  debug: false,
});

export async function middleware(req: NextRequest) {
  await telemetry(req);
  return NextResponse.next();
}

export const config = {
  matcher: [
    // Match all routes except Next.js internals and static files
    "/((?!_next/static|_next/image|favicon.ico).*)",
  ],
};

2. Use environment variables (recommended)

const telemetry = telemetryMiddleware({
  projectId: process.env.TELEMETRY_PROJECT_ID!,
  apiUrl: process.env.TELEMETRY_API_URL,
  serverSecret: process.env.TELEMETRY_SERVER_SECRET!,
});

# .env.local
TELEMETRY_PROJECT_ID=your-project-id
TELEMETRY_API_URL=https://telemetry-uqd3.onrender.com
TELEMETRY_SERVER_SECRET=sk_...

How it works

1. Every request that passes the matcher runs through the middleware
2. The request is normalized (UA, IP, headers) and passed to detectBot()
3. If a bot is detected (or trackAll: true), a payload is sent to the Telemetry API
4. On Vercel Edge / Cloudflare Workers, waitUntil is used so the send happens after the response is sent — zero latency impact
5. On other runtimes, the send is awaited before NextResponse.next() is returned

Configuration options

| Option | Type | Default | Description | |--------|------|---------|-------------| | projectId | string | required | Your Telemetry project ID | | serverSecret | string | required | Your server secret key for API auth | | apiUrl | string | hosted service | Override the API endpoint | | trackAll | boolean | false | Track all requests, not just bots | | trackSearchBots | boolean | true | Include Googlebot, Bingbot etc. | | ignorePaths | (string \| RegExp)[] | — | Paths to skip entirely | | customBots | Array<{name, pattern, category?}> | — | Add custom bot definitions | | debug | boolean | false | Log detection results to the console | | authorizationHeader | string | — | Fully custom Authorization header value | | headers | Record<string, string> | — | Extra headers on every telemetry request |

Examples

Skip API routes and health checks

telemetryMiddleware({
  projectId: "...",
  serverSecret: "sk_...",
  ignorePaths: ["/health", "/ping", /^\/api\//],
});

Track all visitors (not just bots)

telemetryMiddleware({
  projectId: "...",
  serverSecret: "sk_...",
  trackAll: true,
});

Add custom bot definitions

telemetryMiddleware({
  projectId: "...",
  serverSecret: "sk_...",
  customBots: [
    { name: "MyInternalCrawler", pattern: /my-crawler\/\d+/i, category: "scraper" },
  ],
});

What gets tracked

Each bot detection event sends:

| Field | Description | |-------|-------------| | projectId | Your project ID | | path | Request path | | method | HTTP method | | userAgent | Full user-agent string | | ip | Client IP (from x-forwarded-for) | | isBot | true / false | | botName | Named bot e.g. "GPTBot", or null | | botCategory | e.g. "ai-crawler", "search", "scraper" | | confidence | "certain" / "high" / "medium" / "low" | | detectionMethod | "ua-match" / "header-anomaly" / "automation-header" / etc. | | referrer | Referrer header | | timestamp | ISO 8601 UTC |