ua-parser-js: User-Agent and Client Hints Parsing, and What the AGPL v2 Costs You

The problem ua-parser-js solves, and who is asking

A User-Agent header is a single line of text that browsers, bots, apps and crawlers have spent three decades filling with inconsistent tokens. Turning that line into structured fields (browser name and version, rendering engine, operating system, device vendor and model, CPU architecture) is the job ua-parser-js does. The package description states it detects "Browser, Engine, OS, CPU, and Device type/model from User-Agent & Client Hints data" and supports both browser and Node.js environments.

The audience is narrow but large: analytics pipelines that need to bucket traffic by device class, support teams that want to know which browser a bug report came from, and bot-mitigation code that needs to separate a human browser from a crawler. The README also claims detection of apps, libraries, email clients, media players, crawlers and AI crawlers, which pushes it beyond classic browser sniffing into log classification.

If you only need to know whether a request came from a phone, you do not need this library. A media query or a viewport check answers that without parsing anything. The library earns its place when you need the parsed result server-side, on traffic you never rendered, or when you need the same parsing logic in the browser and in Node.

How the parsing actually works: regex database plus Client Hints

The mechanism is a pattern-matching database. The repository keeps its detection rules in src/ and builds distributable bundles into dist/; the package is dependency-free, which is stated in the README's opening line. At call time the library takes a User-Agent string, and optionally Client Hints data, and matches it against that database to produce a result object with browser, engine, os, cpu and device properties.

The v2 line adds Client Hints support, which the README's package comparison table only marks as present in the AGPL v2 column and the PRO columns, not in v1. That matters architecturally: User-Agent strings are being frozen and reduced by browser vendors, so a parser that reads only the header will degrade over time, while one that also consumes the structured hints keeps working. The table also lists ESM support as v2-only, with CommonJS available in both lines.

Because the rules are data, accuracy is a maintenance property rather than an algorithmic one. New browser versions, new device model strings and new crawler identities all require database updates. The last push to the repository was on 2026-09-01, and the most recent release listed is 2.0.10 from 2026-05-21, so the database is being revised between releases. The README refers to an "actively maintained, extensive detection database" without quantifying it.

Installing ua-parser-js and parsing your first User-Agent

The package is published to npm under the name ua-parser-js, which the README's package table confirms for both open-source editions. The README documents version 2.x at docs.uaparser.dev and version 1.x at docs.uaparser.dev/v1, and warns that anyone upgrading from v0.7 or v1.0 should read CHANGELOG.md first because there are breaking changes.

The repository ships a Dockerfile that builds a CLI. Its entrypoint is node ./script/cli.js, and the image runs on node:lts-alpine with production dependencies only. The build stage copies package*.json and runs npm install --omit=dev; the runtime stage copies src, script/cli.js and the installed node_modules:

FROM node:lts-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install --omit=dev

COPY src ./src
COPY script/cli.js ./script/cli.js
COPY --from=builder /app/node_modules ./node_modules
ENTRYPOINT ["node", "./script/cli.js"]
CMD [""]

That gives you a way to parse a User-Agent string without writing a Node script: build the image, then run it with the string as the argument. What you should see is the parsed result printed by the CLI, with browser, engine, os and device fields. Empty fields mean the detection database had no matching rule for that input, which is a normal outcome for unusual or spoofed strings rather than an error.

The README does not print a library call example, so the Dockerfile's entrypoint and the live demo at uaparser.dev are the only concrete usage the repository shows. For the API surface, the README points to docs.uaparser.dev for version 2.x.

Where ua-parser-js breaks down

The first limitation is the input itself. User-Agent strings are client-controlled. A bot can send a Chrome string, and a browser extension can rewrite the header entirely. Any detection field, including the bot and AI crawler categories the README advertises, is an inference from a string the caller chose to send. Treating a positive bot match as authoritative and a negative match as proof of a human is a misuse of the library, not a bug in it.

The second limitation is licence scope. The README's comparison table marks the open-source v2 column as AGPL with "Permissive (non-Copyleft) License" set to no and "No Open-Source Obligations" set to no. The PRO columns exist precisely to offer a permissive licence, alongside 1-year product support. If your legal position is that you cannot take copyleft obligations, the open-source 2.x package is the wrong tool and the PRO editions are the intended path. The README does not document rollback or a migration path back to 1.x once you have adopted 2.x APIs.

Third, the README does not state accuracy rates, coverage percentages or a supported-runtime matrix beyond "browsers, Node.js, and modern JavaScript runtimes". If you need a guarantee about a specific device family, the repository's test/ directory and the live demo at uaparser.dev are the only places to check behaviour before shipping.

ua-parser-js alternatives and the real difference

The most common comparison is with Bowser, which appears in the search data as "bowser vs ua-parser js". Bowser is a smaller, browser-focused parser: it targets browser and OS identification from a User-Agent string and is built for client-side use. ua-parser-js covers a wider field set (CPU, device model, and the extra detection categories the README lists such as apps, email clients, media players and crawlers) and ships a Node-oriented workflow including a Docker CLI. If all you need is "which browser and version", Bowser's narrower scope is a feature, not a gap.

The other genuine alternative is not another library but the platform. Client Hints are a browser API, and reading them directly avoids a dependency entirely. The catch is that Client Hints require server cooperation through Accept-CH headers and are not available for traffic that never runs the API, such as log files. ua-parser-js exists in the space between those two: it consumes hints when present and falls back to string parsing when they are not.

For teams already on ua-parser-js 1.x, the meaningful comparison is with your own current version. The README's table shows 1.x as MIT-licensed, CommonJS-only, without bot detection, AI detection or Client Hints support. The upgrade buys detection breadth and ESM; it costs you the permissive licence.

Licence, maintenance and upgrade cost

Version 2.x is AGPL-3.0 per the repository licence identifier and the README table. The README labels the v1.x line MIT and the v2.x line AGPL, and explicitly marks the v2 open-source column as copyleft with open-source obligations. AGPL is a network-copyleft licence, so the obligations attach to software offered over a network, which is exactly the deployment shape of most server-side User-Agent parsing. This article is not legal advice; the operative documents are LICENSE.md in the repository root and the per-edition license.md files the README links for PRO Personal, PRO Business and PRO Enterprise.

Maintenance cost is mostly database drift. The last push was on 2026-09-01, and releases arrive on a multi-month cadence (2.0.8 in January 2026, 2.0.9 in February, 2.0.10 in May). If your product depends on recognising new device models or new crawlers quickly, you are tied to that cadence or to your own patches. The README promises lifetime updates for both open-source and PRO editions, but not a release schedule.

Upgrade cost from v0.7 or v1.0 is a breaking-change exercise: the README directs you to CHANGELOG.md before upgrading, and the module format changes (ESM appears in v2 only). The repository also carries SECURITY.md, INCIDENT_RESPONSE.md and THIRD_PARTY_NOTICES.md at the top level, which is unusual for a package of this size and reflects the project's history.

Editorial conclusion

Adopt ua-parser-js 2.x if your project can live with AGPL-3.0, or if you are already on the MIT 1.x line and do not need bot, AI crawler or Client Hints detection. Do not adopt 2.x inside a closed-source product without reading LICENSE.md and the PRO license files first, because the README lists a non-Copyleft license as a PRO feature and marks the open-source 2.x column as copyleft. Before committing, confirm which detection fields your code actually reads, check whether your runtime can load the ESM or CommonJS build, and run the CLI over a sample of your real log lines to see how many fields come back empty.

Frequently asked questions

Official sources

1. faisalman/ua-parser-js on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases