@arraypress/user-agent

Parse user agent strings to detect browsers, operating systems, device types, and bots. Designed for analytics, admin dashboards, and download tracking.

Zero dependencies. Works in Node.js, Cloudflare Workers, Deno, Bun, and browsers.

Installation

npm install @arraypress/user-agent

Usage

import { parse, getBrowser, getOS, getDevice, isBot, format } from '@arraypress/user-agent';

// Parse everything at once
const ua = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ... Chrome/120.0.0.0 Safari/537.36';
parse(ua);
// { browser: 'Chrome', os: 'macOS', device: 'desktop', isBot: false }

// Individual functions
getBrowser(ua);  // 'Chrome'
getOS(ua);       // 'macOS'
getDevice(ua);   // 'desktop'
isBot(ua);       // false

// Human-readable format for display
format(ua);      // 'Chrome on macOS'

// Bot detection
isBot('Googlebot/2.1');  // true
isBot('GPTBot/1.0');     // true
isBot('curl/8.4.0');     // true

API

parse(ua: string): ParsedUserAgent

Parse a user agent string into all components in one call. Returns:

interface ParsedUserAgent {
  browser: string | null;   // 'Chrome', 'Safari Mobile', 'Edge', etc.
  os: string | null;        // 'macOS', 'Windows', 'iOS', 'Android', etc.
  device: DeviceType;       // 'desktop', 'mobile', 'tablet', 'bot', 'unknown'
  isBot: boolean;
}

getBrowser(ua: string): string | null

Returns the browser name. Correctly distinguishes Chrome-based browsers (Edge, Opera, Brave, Vivaldi, Samsung Browser are detected individually, not as Chrome).

getOS(ua: string): string | null

Returns the operating system name.

getDevice(ua: string): DeviceType

Returns the device type: 'desktop', 'mobile', 'tablet', 'bot', or 'unknown'. Tablets (iPad, Android tablets) are categorised separately from mobile phones.

isBot(ua: string): boolean

Detects search engine bots, AI/LLM crawlers, social media bots, SEO tools, and programmatic HTTP clients.

format(ua: string): string

Returns a human-readable string like "Chrome on macOS" or "Safari Mobile on iOS". Useful for display in admin panels and download logs.

Detected Browsers

Chrome, Chrome Mobile, Chrome iOS, Chrome OS, Firefox, Firefox iOS, Safari, Safari Mobile, Edge, Opera, Brave, Vivaldi, Samsung Browser, UC Browser, DuckDuckGo iOS, Internet Explorer, Android WebView, Electron.

Detected Operating Systems

Windows, macOS, iOS, Android, Linux, Ubuntu, Chrome OS.

Detected Bots

Search engines: Googlebot, Bingbot, Baiduspider, DuckDuckBot, YandexBot, Applebot.

AI/LLM: GPTBot, ChatGPT-User, ClaudeBot, PerplexityBot, Bytespider, Anthropic-AI.

Social: Facebook, Twitter, LinkedIn, WhatsApp, Telegram, Slack, Discord.

Tools: SemrushBot, AhrefsBot, curl, wget, Postman, axios, python-requests.

TypeScript

Full type definitions included.

import { parse, isBot } from '@arraypress/user-agent';
import type { ParsedUserAgent, DeviceType } from '@arraypress/user-agent';

const result: ParsedUserAgent = parse(ua);
const device: DeviceType = result.device;

License

MIT