getBotDetection()
Introduction
Type: function getBotDetection(event: H3Event): BotDetectionContext
Perform bot detection using request headers in server-side Nitro routes, middleware, and API handlers.
This function analyzes HTTP headers to detect known bots and returns detailed classification information.
🔔 Important: Bot detection only runs when you explicitly call these utility functions. No automatic bot detection occurs - it's entirely opt-in based on your usage of these functions.
Usage
Basic Detection
// server/api/example.ts
import { getBotDetection } from '#robots/server/composables/getBotDetection'
import { defineEventHandler } from 'h3'
export default defineEventHandler(async (event) => {
const detection = getBotDetection(event)
if (detection.isBot) {
return { message: 'Bot detected', bot: detection.botName }
}
return { message: 'Human user' }
})
Helper Functions
// server/api/bot-check.ts
import { getBotInfo, isBot } from '#robots/server/composables/getBotDetection'
import { defineEventHandler } from 'h3'
export default defineEventHandler(async (event) => {
// Simple boolean check
if (isBot(event)) {
return { isBot: true }
}
// Get detailed bot info
const botInfo = getBotInfo(event)
return { isBot: false, info: botInfo }
})
Middleware Usage
// middleware/bot-filter.ts
import { getBotDetection } from '#robots/server/composables/getBotDetection'
import { createError, defineEventHandler } from 'h3'
export default defineEventHandler(async (event) => {
const detection = getBotDetection(event)
// Block untrusted bots from API routes
if (event.node.req.url?.startsWith('/api/') && detection.isBot && !detection.trusted) {
throw createError({
statusCode: 403,
statusMessage: 'Bot access denied'
})
}
})
Return Type
getBotDetection()
Returns the complete bot detection context:
interface BotDetectionContext {
isBot: boolean
userAgent?: string
detectionMethod?: 'headers' | 'fingerprint'
botName?: BotName // 'googlebot', 'twitterbot', 'claude', etc.
botCategory?: BotCategory // 'search-engine', 'social', 'ai', etc.
trusted?: boolean // Whether this is a legitimate bot
}
isBot()
Type: function isBot(event: H3Event): boolean
Simple boolean check for bot detection.
getBotInfo()
Type: function getBotInfo(event: H3Event): BotInfo | null
Returns bot details if detected:
interface BotInfo {
name?: BotName // Specific bot name ('googlebot', 'facebook', etc.)
category?: BotCategory // Bot category ('search-engine', 'social', etc.)
trusted?: boolean // Legitimacy flag
method?: 'server' | 'fingerprint' // Detection method
}
Detection Methods
- server: Detected via HTTP headers and user agent analysis
- fingerprint: Detected via client-side browser fingerprinting (only available after client hydration)
Availability
The bot detection state is available:
- ✅ Server routes: Immediately available
- ✅ API handlers: Immediately available
- ✅ Middleware: Immediately available
- ✅ Server plugins: Immediately available
Note that client-side fingerprint detection results are only available after the client has loaded and run the detection.
Pure Utility Functions
For use outside of Nuxt/Nitro contexts, import from /util:
import { getBotDetection, getBotInfo, isBot } from '@nuxtjs/robots/util'
// Works with any headers object
const headers = { 'user-agent': 'Mozilla/5.0 (compatible; Googlebot/2.1)' }
const detection = getBotDetection(headers)
// { isBot: true, botName: 'googlebot', botCategory: 'search-engine', ... }
const isBotDetected = isBot(headers)
// true
const botInfo = getBotInfo(headers)
// { name: 'googlebot', category: 'search-engine', trusted: true, method: 'server' }
These pure functions work in any JavaScript environment and don't require H3 events or Nuxt context.