Skip to content

client-parser

packageLast commit

A tiny, type-safe client classifier with User-Agent, Client Hints, and HTTP header support.

Open productSource
Role
Library design and package engineering
Scope
Typed APIs, compatibility, and package distribution
Status
Pre-1.0 package
client-parser interface preview

Problem

Analytics and diagnostics need a normalized view of client strings and hints, while many parsers are heavy or encourage unsafe use of inherently heuristic data.

Constraints

  1. C1

    User-Agent classification is heuristic and spoofable.

  2. C2

    Client Hints availability varies and may be privacy-restricted.

  3. C3

    Results cannot safely drive authentication, authorization, or capability decisions.

Architecture

Pure parsing/normalization rules and typed result model; zero-dependency dual-module package; workspace-linked playground/docs and regression corpus.

01

Core library

Pure parsing/normalization rules and typed result model.

02

Package builds

Zero-dependency dual-module package.

03

Documentation app

Workspace-linked playground/docs and regression corpus.

Decisions

D1

State the heuristic boundary explicitly and recommend feature detection for behavior

State the heuristic boundary explicitly and recommend feature detection for behavior.

D2

Combine User-Agent and Client Hints through one normalized output

Combine User-Agent and Client Hints through one normalized output.

D3

Remain zero dependency and pre-1.0

Remain zero dependency and pre-1.0, accepting a maintained rule/test corpus and changelog review.

Contribution

  • Implemented browser, OS, device, mobile, and bot classification.
  • Added Client Hints support and normalized typed results.
  • Created representative regression tests and package builds.
  • Built a local-input playground without requiring a server parser.

Outcomes

  • Consumers can classify common client strings.
  • Enrich results with available hints.
  • Distinguish bots/devices/browsers for analytics or presentation.
  • Inspect parsing behavior interactively.

Product screenshot

client-parser interface preview
client-parser presents a tiny, type-safe client classifier with User-Agent, Client Hints, and HTTP header support.

Verified stack

  • TypeScript
  • ESM
  • CommonJS
  • tsup
  • TanStack Start
  • React
  • Tailwind CSS
  • Vite
  • Vitest
  • Netlify
  • GitHub Actions
  • CI/CD

Working through something similar?

Share your challenge, scope, and timeline to start a focused conversation.