Documentation / Overview

Classify clients from the evidence you actually have.

client-parser is a tiny, type-safe client classifier for User-Agent strings, Client Hints, and HTTP headers. It reports what it found, where it found it, and how confident the classification is.

Zero dependenciesNode 18+ESM + CommonJSTypeScript

Use classification responsibly.

Use these signals for analytics, diagnostics, and presentation hints—not authentication, authorization, or browser capability checks.

Installation

Install from npm with your preferred package manager.

$ npm install client-parser

Quick start

Pass a User-Agent string to parseClient. Unavailable details are omitted rather than filled with placeholders.

TypeScript

import { parseClient } from 'client-parser'

const client = parseClient(
  'Mozilla/5.0 (iPhone; CPU iPhone OS 17_5...)',
)

console.log(client.device.type)  // "mobile"
console.log(client.browser.name) // "Chrome"
console.log(client.os.name)      // "iOS"
console.log(client.engine.name)  // "WebKit"
console.log(client.isMobile)     // true

The default export is also parseClient. CommonJS consumers can use require('client-parser').

Server-side header parsing

Pass a plain header object or any object with a Headers-compatible get() method. Header names are case-insensitive.

server.ts

import { parseClient } from 'client-parser'

const client = parseClient({
  headers: request.headers,
})

Supported headers include Sec-CH-UA, full versions, mobile, platform, architecture, bitness, model, and WoW64.

Browser Client Hints

parseNavigator collects high-entropy hints when available and falls back gracefully when they are denied or unsupported.

browser.ts

import { parseNavigator } from 'client-parser'

const client = await parseNavigator(navigator)

High-entropy hints are conditional.

The browser and server policy decide which values are exposed. Always expect a partial result.

API reference

parseClient(input?)

Synchronously classifies a User-Agent string or a ClientEvidence object.

parseNavigator(navigatorLike)

Asynchronously collects browser evidence and classifies the result.

parseClientHintHeaders(headers)

Normalizes Sec-CH-UA-* headers into the Client Hints shape.

getDeviceType(input?)deprecated

Compatibility alias for parseClient. Use the new name in new code.

Result shape

The stable top-level result lets consumers use narrow signals without reparsing raw input.

devicetype, name, vendor, model

browsername, version, major

osname, version, architecture

enginename, version

botisBot, name, category

sourceuser-agent, client-hints, headers, platform

confidencehigh, medium, low

Accuracy & privacy

User-Agent strings can be reduced, spoofed, or ambiguous. Client Hints are structured but not universal. Use source and confidence to account for those limits.

✓No network requests
✓No stored data
✓No runtime dependencies
✓User-Agent capped at 8 KiB

Migrate from 0.0.x

→Replace getDeviceType() with parseClient().
→Read bot status from result.bot.isBot.
→Expect form-factor device types such as mobile, tablet, and desktop.
→Handle absent optional fields instead of “unknown” placeholders.
→Import public TypeScript types directly from client-parser.

Open the playground