or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-isbot

Recognise bots/crawlers/spiders using the user agent string.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/isbot@5.1.x

To install, run

npx @tessl/cli install tessl/npm-isbot@5.1.0

index.mddocs/

isbot

isbot is a comprehensive bot detection library that identifies bots, crawlers, and spiders by analyzing user agent strings. It provides both simple boolean detection and advanced pattern matching capabilities, supporting multiple JavaScript environments with high accuracy and zero runtime dependencies.

Package Information

  • Package Name: isbot
  • Package Type: npm
  • Language: TypeScript/JavaScript
  • Installation: npm install isbot

Core Imports

import { isbot } from "isbot";

For all exports:

import { 
  isbot, 
  isbotNaive, 
  isbotMatch, 
  isbotMatches, 
  isbotPattern, 
  isbotPatterns,
  createIsbot, 
  createIsbotFromList, 
  getPattern, 
  list 
} from "isbot";

CommonJS:

const { isbot } = require("isbot");
const { isbot, list, createIsbot } = require("isbot");

Browser (global):

<script src="https://cdn.jsdelivr.net/npm/isbot@5.1.30/index.iife.js"></script>
<script>
  console.log(isbot(navigator.userAgent));
</script>

Basic Usage

import { isbot } from "isbot";

// Basic bot detection
const userAgent = "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)";
console.log(isbot(userAgent)); // true

// Real browser user agent
const browserAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36";
console.log(isbot(browserAgent)); // false

// Handle null/undefined gracefully
console.log(isbot(null)); // false
console.log(isbot(undefined)); // false
console.log(isbot("")); // false

Architecture

isbot is built around several key components:

  • Pattern Engine: Comprehensive regex patterns compiled from a curated list of bot identifiers
  • Fallback System: Naive pattern matching as fallback for environments with regex limitations
  • Factory Functions: Customizable bot detection with user-defined patterns
  • Multiple Exports: Support for CommonJS, ESM, and browser environments
  • Zero Dependencies: Standalone library with no external dependencies

Capabilities

Core Bot Detection

Primary bot detection functionality using comprehensive pattern matching.

/**
 * Check if the given user agent includes a bot pattern.
 * Uses comprehensive pattern matching for high accuracy.
 */
function isbot(userAgent?: string | null): boolean;

Naive Bot Detection

Fast, simple bot detection using basic pattern matching.

/**
 * Check if the given user agent includes a bot pattern. 
 * Naive implementation (less accurate but faster).
 */
const isbotNaive: (userAgent?: string | null) => boolean;

Pattern Matching

Find specific parts of user agents that match bot patterns.

/**
 * Find the first part of the user agent that matches a bot pattern.
 */
const isbotMatch: (userAgent?: string | null) => string | null;

/**
 * Find all parts of the user agent that match bot patterns.
 */
const isbotMatches: (userAgent?: string | null) => string[];

Pattern Discovery

Identify which specific patterns from the bot list match a user agent.

/**
 * Find the first bot pattern that matches the given user agent.
 */
const isbotPattern: (userAgent?: string | null) => string | null;

/**
 * Find all bot patterns that match the given user agent.
 */
const isbotPatterns: (userAgent?: string | null) => string[];

Usage Examples:

import { isbotMatch, isbotMatches, isbotPattern, isbotPatterns } from "isbot";

const botUA = "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)";

// Find first matching substring using compiled pattern
console.log(isbotMatch(botUA)); // "google" (first match from combined pattern)

// Find all matching substrings from individual patterns
console.log(isbotMatches(botUA)); // ["google", "bot", "compatible"] (various matches)

// Find first matching pattern string from the pattern list
console.log(isbotPattern(botUA)); // "(?<! (?:channel/|google/))google(?!(app|/google| pixel))"

// Find all matching pattern strings from the pattern list
console.log(isbotPatterns(botUA)); // Array of pattern strings that match

Custom Bot Detection

Create custom bot detection functions with user-defined patterns.

/**
 * Create a custom isbot function with a custom RegExp pattern.
 */
const createIsbot: (customPattern: RegExp) => ((userAgent?: string | null) => boolean);

/**
 * Create a custom isbot function from a list of pattern strings.
 * @param list - Array of regex pattern strings to match against user agents
 */
const createIsbotFromList: (list: string[]) => ((userAgent?: string | null) => boolean);

Usage Examples:

import { createIsbot, createIsbotFromList } from "isbot";

// Custom regex pattern
const customBot = createIsbot(/my-custom-bot|special-crawler/i);
console.log(customBot("My-Custom-Bot/1.0")); // true
console.log(customBot(null)); // false - handles null/undefined gracefully

// From pattern list - array of regex pattern strings
const socialBots = createIsbotFromList([
  "facebookexternalhit",
  "twitterbot", 
  "linkedinbot"
]);
console.log(socialBots("facebookexternalhit/1.1")); // true
console.log(socialBots("")); // false - handles empty strings gracefully

Pattern Access

Access to the underlying patterns and regex used for detection.

/**
 * Returns the compiled RegExp pattern used for bot detection.
 * Falls back to naive pattern if compilation fails.
 */
function getPattern(): RegExp;

/**
 * A list of bot identifiers used in regular expressions against user agent strings.
 */
const list: string[];

Usage Examples:

import { getPattern, list } from "isbot";

// Get the compiled pattern
const pattern = getPattern();
console.log(pattern.test("Googlebot/2.1")); // true

// Access pattern list - contains regex pattern strings
console.log(list.length); // 200+ regex patterns
console.log(list.includes("(?<! (?:channel/|google/))google(?!(app|/google| pixel))")); // true

// Use patterns directly
const hasGooglePattern = list.some(patternStr => 
  new RegExp(patternStr, "i").test("Googlebot/2.1 (+http://www.google.com/bot.html)")
); // true

Error Handling

isbot handles edge cases gracefully:

  • Null/undefined user agents: Returns false safely
  • Empty strings: Returns false
  • Invalid regex patterns: Falls back to naive pattern matching
  • Older JavaScript engines: Graceful degradation to simple pattern matching
import { isbot } from "isbot";

// All return false safely
console.log(isbot(null));      // false
console.log(isbot(undefined)); // false  
console.log(isbot(""));        // false

Types

// Main detection function
declare function isbot(userAgent?: string | null): boolean;

// Naive detection
declare const isbotNaive: (userAgent?: string | null) => boolean;

// Pattern matching functions
declare const isbotMatch: (userAgent?: string | null) => string | null;
declare const isbotMatches: (userAgent?: string | null) => string[];
declare const isbotPattern: (userAgent?: string | null) => string | null;
declare const isbotPatterns: (userAgent?: string | null) => string[];

// Factory functions
declare const createIsbot: (customPattern: RegExp) => ((userAgent?: string | null) => boolean);
declare const createIsbotFromList: (list: string[]) => ((userAgent?: string | null) => boolean);

// Utility functions
declare function getPattern(): RegExp;
declare const list: string[];