isbot

isbot is a tiny, zero-dependency JavaScript and TypeScript library that identifies bots, crawlers, and spiders by testing the request’s user agent string against a large, regularly updated pattern list. It exposes a single isBot function plus a family of helpers for matching, customization, and building your own detectors, and runs identically in Node.js, browsers, and edge runtimes.

Rather than trying to unmask malicious bots, isbot focuses on reliably recognising “good bots” that voluntarily identify themselves — search-engine crawlers, previews, scrapers, and monitoring agents. The pattern is compiled from expansive community-maintained data sources and ships with a naive fallback for engines that lack regular-expression lookbehind support.

What You Get

• A single isBot(userAgent) function returning a boolean for any user agent string
• A community-maintained, regularly updated pattern list compiled from multiple external data sources
• Named helpers to find matched substrings and patterns, and to build custom detectors
• ESM, CommonJS, and UMD/CDN builds that run in Node.js, browsers, and edge runtimes with zero runtime dependencies

Common Use Cases

• Flagging or excluding bot pageviews in analytics and business reporting
• Serving cached content or lighter responses to crawlers to relieve service load
• Omitting third-party tags and pixels for bots to reduce costs
• Customizing detection to include or exclude specific agents such as Chrome Lighthouse

Under The Hood

Architecture isbot is built around a single lazily-compiled regular expression. src/index.ts imports a large patterns.json substring list and a precomputed fullPattern, then getPattern() compiles that pattern into a case-insensitive RegExp on first use, memoizes it, and falls back to a small naive pattern (/bot|crawl|http|lighthouse|scan|search|spider/i) if the engine cannot compile the full expression (it relies on lookbehind). isBot(userAgent) simply guards for a non-empty string and tests it against the pattern; helper exports like findBotMatch, findBotPatterns, createIsBotFromList, and legacy aliases are thin functions over the same list and regex. src/browser.ts attaches isBot to the global object for the UMD/CDN build.

Tech Stack The source is TypeScript targeting Node.js >=18, bundled with tsup into CommonJS, ESM, and a browser global build, with type declarations emitted. There are zero runtime dependencies; devDependencies cover jest and ts-jest for testing, prettier for formatting, pug for the docs page, and a user-agents dataset for test fixtures. Build, test, and format are driven by shell scripts under scripts/.

Code Quality The library is small and strongly typed, with explicit narrowing helpers (isNonEmptyString) and JSDoc on every export. A real test suite lives under tests/ with a spec suite plus committed snapshots and a dedicated efficiency test, and fixtures under fixtures/ exercise real bot and non-bot user agent samples. Accuracy is explicitly managed with documented tolerances for the fallback path (1% false positives, 75% coverage).

API Design The public surface is deliberately ergonomic: the primary path is one intuitively named isBot(userAgent) call, while power users get a coherent family of findBot* introspection helpers and createIsBot/createIsBotFromList factories for custom detection. Naming is consistent, backward-compatibility aliases ease major-version upgrades, and the README documents every named import in a single table with copy-paste examples, so getting started requires essentially no boilerplate.