How to Block AI Bots on Nitro: Complete 2026 Guide

Step 1 — Shared util (server/utils/ai-bots.ts)

Files in server/utils/ are auto-imported by Nitro — no import statement needed in your plugins or handlers (though explicit imports work too).

// server/utils/ai-bots.ts
export const AI_BOTS = [
  // OpenAI
  'gptbot', 'chatgpt-user', 'oai-searchbot',
  // Anthropic
  'claudebot', 'claude-web',
  // Common Crawl
  'ccbot',
  // Bytedance
  'bytespider',
  // Meta
  'meta-externalagent',
  // Perplexity
  'perplexitybot',
  // Google AI
  'google-extended', 'googleother',
  // Cohere
  'cohere-ai',
  // Amazon
  'amazonbot',
  // Diffbot
  'diffbot',
  // AI2
  'ai2bot',
  // DeepSeek
  'deepseekbot',
  // Mistral
  'mistralai-user',
  // xAI
  'xai-bot',
  // You.com
  'youbot',
  // DuckDuckGo AI
  'duckassistbot',
] as const;

export function isAiBot(userAgent: string | null | undefined): boolean {
  if (!userAgent) return false;
  const ua = userAgent.toLowerCase();
  return AI_BOTS.some((bot) => ua.includes(bot));
}

Step 2A — Plugin-based global blocker

Nitro auto-loads all files in plugins/ at startup. The 'request' hook fires on every incoming request before routing.

// plugins/block-bots.ts
// Runs once at startup — registers a request hook that fires on every request
import { isAiBot } from '~/server/utils/ai-bots';

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('request', async (event) => {
    const ua = getRequestHeader(event, 'user-agent');

    // 1. Block AI bots with a hard 403
    if (isAiBot(ua)) {
      throw createError({
        statusCode: 403,
        statusMessage: 'Forbidden',
      });
    }

    // 2. Set X-Robots-Tag on all non-blocked responses
    //    (fires before route handler returns, so it applies to all responses)
    setResponseHeader(event, 'X-Robots-Tag', 'noai, noimageai');
  });
});

Step 2B — Middleware-based global blocker (alternative)

Create server/middleware/block-bots.ts. Nitro auto-runs all files in server/middleware/on every request, in alphabetical order, before route handlers. Use this or the plugin — not both.

// server/middleware/block-bots.ts
// Nitro auto-runs all files in server/middleware/ on every request, in alphabetical order.
// This file runs before any route handler.
import { isAiBot } from '~/server/utils/ai-bots';

export default defineEventHandler((event) => {
  const ua = getRequestHeader(event, 'user-agent');

  if (isAiBot(ua)) {
    throw createError({
      statusCode: 403,
      statusMessage: 'Forbidden',
    });
  }

  // Add X-Robots-Tag to every response that passes the UA check
  setResponseHeader(event, 'X-Robots-Tag', 'noai, noimageai');
});

Step 3 — robots.txt route

Nitro maps server/routes/robots.txt.ts to GET /robots.txt automatically. No router configuration needed. Alternatively, place a static robots.txt in public/ — static files are served before server routes.

// server/routes/robots.txt.ts
// Nitro maps server/routes/robots.txt.ts → GET /robots.txt automatically.
// No router config needed — the filename IS the route.

const ROBOTS_CONTENT = `User-agent: *
Allow: /

# AI training bots — blocked
User-agent: GPTBot
Disallow: /

User-agent: ClaudeBot
Disallow: /

User-agent: CCBot
Disallow: /

User-agent: Bytespider
Disallow: /

User-agent: Google-Extended
Disallow: /

User-agent: PerplexityBot
Disallow: /

User-agent: Meta-ExternalAgent
Disallow: /

User-agent: YouBot
Disallow: /

User-agent: AmazonBot
Disallow: /

User-agent: Diffbot
Disallow: /`;

export default defineEventHandler((event) => {
  setResponseHeader(event, 'Content-Type', 'text/plain; charset=utf-8');
  setResponseHeader(event, 'Cache-Control', 'public, max-age=86400');
  return ROBOTS_CONTENT;
});

Step 4 — Per-route blocking (optional)

When you only want to block AI bots on specific API routes, skip the global middleware and check inline. Useful for protecting a /api/private endpoint while leaving /api/public open.

// server/api/data.get.ts — per-route bot blocking
// Use when you want to block AI bots on specific routes only,
// not globally. The global middleware is simpler for most use cases.
import { isAiBot } from '~/server/utils/ai-bots';

export default defineEventHandler((event) => {
  if (isAiBot(getRequestHeader(event, 'user-agent'))) {
    throw createError({ statusCode: 403, statusMessage: 'Forbidden' });
  }

  // Your route logic here
  return { data: 'protected content' };
});

Step 5 — Dynamic block-list via useStorage()

Nitro's built-in useStorage() works with filesystem, Redis, Cloudflare KV, and other drivers. Store your block-list there and update it without a server restart. A TTL cache keeps DB reads off the hot path.

// plugins/block-bots-dynamic.ts — block-list from a DB or KV
// Module-level cache — persists for the lifetime of the server process
let cachedBotList: string[] | null = null;
let cacheExpiresAt = 0;
const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes

async function getBotList(storage: Storage): Promise<string[]> {
  const now = Date.now();
  if (cachedBotList && now < cacheExpiresAt) return cachedBotList;

  // Read from Nitro storage (file-system, Redis, KV, etc.)
  const raw = await storage.getItem<string[]>('blocked:bots');
  cachedBotList = raw ?? ['gptbot', 'claudebot', 'ccbot', 'bytespider'];
  cacheExpiresAt = now + CACHE_TTL_MS;
  return cachedBotList;
}

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('request', async (event) => {
    const ua = getRequestHeader(event, 'user-agent')?.toLowerCase() ?? '';
    const botList = await getBotList(useStorage());

    if (botList.some((pattern) => ua.includes(pattern))) {
      throw createError({ statusCode: 403, statusMessage: 'Forbidden' });
    }

    setResponseHeader(event, 'X-Robots-Tag', 'noai, noimageai');
  });
});

// Update block-list without restart:
// await useStorage().setItem('blocked:bots', ['gptbot', 'claudebot', 'newbot'])

Nitro vs Hono vs Bun vs Cloudflare Workers

FAQ