useBotDetection()
Introduction
Type: function useBotDetection(options?: UseBotDetectionOptions): UseBotDetectionReturn
import type { UseBotDetectionOptions, UseBotDetectionReturn } from '@nuxtjs/robots/util'
Detect and classify bots using server-side header analysis and optional client-side browser fingerprinting.
The composable provides reactive access to bot detection results with automatic caching. Client-side fingerprinting is opt-in due to performance costs.
🔔 Important: Bot detection only runs when you use this composable. No automatic bot detection occurs - it's entirely opt-in based on your usage of this composable.
Usage
Basic detection:
import { useBotDetection } from '#robots/app/composables/useBotDetection'
const { isBot, botName, botCategory, trusted } = useBotDetection()
// isBot: ComputedRef<boolean>
// botName: ComputedRef<BotName | undefined> // 'googlebot', 'facebook', etc.
// botCategory: ComputedRef<BotCategory | undefined> // 'search-engine', 'social', etc.
// trusted: ComputedRef<boolean | undefined>
With fingerprinting:
import { useBotDetection } from '#robots/app/composables/useBotDetection'
const { isBot, botName, botCategory, trusted, reset } = useBotDetection({
fingerprint: true,
onFingerprintError: (error) => {
console.error('Fingerprint error:', error)
},
onFingerprintResult: (result) => {
console.log('Fingerprinting completed:', result)
}
})
Watching for changes:
import { useBotDetection } from '#robots/app/composables/useBotDetection'
import { watch } from 'vue'
const { isBot, botName, botCategory } = useBotDetection()
watch(isBot, (detected) => {
if (detected) {
console.log(`Bot: ${botName.value} (${botCategory.value})`)
}
})
Options
interface UseBotDetectionOptions {
fingerprint?: boolean
onFingerprintError?: (error: Error) => void
onFingerprintResult?: (result: BotDetectionContext | null) => void
}
fingerprint
Type: booleanDefault: false
Enable automatic client-side fingerprinting when no bot is detected server-side.
onFingerprintError
Type: (error: Error) => void
Error handler for fingerprinting failures.
onFingerprintResult
Type: (result: BotDetectionContext | null) => void
Callback that fires when fingerprinting completes, providing the final detection result.
Return Type
interface UseBotDetectionReturn {
isBot: ComputedRef<boolean>
botName: ComputedRef<BotName | undefined>
botCategory: ComputedRef<BotCategory | undefined>
trusted: ComputedRef<boolean | undefined>
reset: () => void
}
Return Value
isBot
Type: ComputedRef<boolean>
Reactive boolean indicating whether a bot was detected.
botName
Type: ComputedRef<BotName | undefined>
The specific bot identity (e.g., 'googlebot', 'facebook', 'claude', 'selenium'). undefined if no bot detected.
botCategory
Type: ComputedRef<BotCategory | undefined>
The bot category/purpose (e.g., 'search-engine', 'social', 'ai', 'automation'). undefined if no bot detected.
trusted
Type: ComputedRef<boolean | undefined>
Whether the detected bot is considered trusted. undefined if no bot detected.
reset()
Type: () => void
Clear all detection state and cached results.
Server Side Behavior
On the server, bot detection runs when you use the composable:
import { useBotDetection } from '#robots/app/composables/useBotDetection'
// Only runs when composable is used
const { isBot, botName, botCategory } = useBotDetection()
if (isBot.value) {
// Bot detected via server-side analysis
console.log('Bot:', botName.value, 'Category:', botCategory.value)
}
Client Side Behavior
Client-side fingerprinting is automatic when enabled:
import { useBotDetection } from '#robots/app/composables/useBotDetection'
const { isBot, botName, botCategory } = useBotDetection({
fingerprint: true,
onFingerprintError: (error) => {
console.error('Fingerprinting failed:', error)
}
})
// Fingerprinting runs automatically if no server detection occurred
Configuration
Disabling Bot Detection
You can disable the entire bot detection plugin:
// nuxt.config.ts
import { defineNuxtConfig } from 'nuxt/config'
export default defineNuxtConfig({
robots: {
botDetection: false
}
})
When disabled, the useBotDetection composable will not be available.
Bot Categories
The following bot types are detected:
- search-engine: Google, Bing, Yandex crawlers
- social: Twitter, Facebook, LinkedIn bots
- seo: Ahrefs, SEMrush, Majestic tools
- ai: GPT, Claude, Perplexity crawlers
- automation: Selenium, Puppeteer, WebDriver
- security-scanner: nmap, Nikto, ZGrab
- http-tool: curl, wget, Python requests