@kanadi/user-agent

A lightweight TypeScript library for detecting bot user agents by comparing against a comprehensive pattern database.

Features

• Detect bot user agents from a large database of known bot patterns
• Get detailed information about detected bots including pattern and documentation URL
• Regex pattern caching for optimal performance
• TypeScript support with full type definitions
• Zero dependencies
• Works with Bun, Node.js, and browsers

Installation

bun add @kanadi/user-agent

Usage

import { isBotUserAgent, getUserAgentDetail } from '@kanadi/user-agent';

// Simple bot detection
const isBot = isBotUserAgent('Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)');
console.log(isBot); // true

// Get detailed information
const detail = getUserAgentDetail('Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)');
console.log(detail);
// {
//   isBot: true,
//   pattern: 'Googlebot\\/',
//   url: 'http://www.google.com/bot.html',
//   matchedPattern: /Googlebot\//i
// }

API

isBotUserAgent(userAgent: string): boolean

Check if a user agent string belongs to a bot.

Parameters:

• userAgent - The user agent string to check

Returns:

• true if the user agent is a bot, false otherwise

getUserAgentDetail(userAgent: string): UserAgentDetail

Get detailed information about a user agent.

Parameters:

• userAgent - The user agent string to analyze

Returns: An object with the following properties:

• isBot: boolean - Whether the user agent is a bot
• pattern?: string - The regex pattern that matched (if bot)
• url?: string - Documentation URL for the bot (if available)
• matchedPattern?: RegExp - The compiled regex pattern (if bot)

Examples

See the examples/ directory for more usage examples.

Run the example:

cd examples
bun index.ts

License

This project uses code from monperrus/crawler-user-agents, licensed under the MIT License. See LICENSE file for more details.