Registry / http-networking / ua-parser-js

ua-parser-js

library2.0.9jsnpmunverified

UAParser.js is a comprehensive JavaScript library designed for detecting detailed information about a user's browser, operating system, CPU architecture, and device type/model. It leverages both traditional User-Agent strings and modern Client Hints data for accurate analysis. The current stable version is 2.0.9, with frequent patch releases indicating active development and continuous updates to its detection database for new browsers, OSes, and devices. This library is distinguished by its robust support for both client-side (browser) and server-side (Node.js) environments, offering a unified API. Key differentiators include its detailed detection capabilities, compact size, and up-to-date definitions, including specific submodules for bot and crawler detection, as well as features for chaining `withClientHints()` and `withFeatureCheck()`. A critical aspect for users is the change in licensing: while version 1.x was released under the permissive MIT License, version 2.x and onwards are distributed under the AGPL-3.0 License, which has significant implications for commercial and open-source projects.

http-networking web-framework

npm install ua-parser-js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · UA-PARSER-JS

ua-parser-js

http-networkingjavascriptv2.0.9

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

UAParser

✓ import UAParser from 'ua-parser-js';

✗ import { UAParser } from 'ua-parser-js';

The UAParser class is exported as the default export since version 2.x. For CommonJS, use `const UAParser = require('ua-parser-js');`.

IResult

✓ import type { IResult } from 'ua-parser-js';

Import TypeScript types separately for type safety.

isBot

✓ import { isBot } from 'ua-parser-js/extensions/bot-detection';

✗ import { isBot } from 'ua-parser-js';

Utility functions like `isBot` are part of specific submodules under `extensions` and must be imported from their dedicated paths.

UAParser CommonJS

✓ const UAParser = require('ua-parser-js');

This is the correct CommonJS `require` syntax for the default export. Mixing this with ESM `import` in hybrid environments can lead to issues.

This quickstart demonstrates parsing a user-agent string, utilizing client hints for richer detection (relevant in server-side Node.js applications), and using a utility function from the 'extensions' submodule to check for bots. It highlights the primary API for both traditional and modern detection methods.

import UAParser from 'ua-parser-js'; import type { IResult } from 'ua-parser-js'; // Example 1: Parsing a standard User-Agent string const userAgentString = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36'; const parser = new UAParser(userAgentString); const result1: IResult = parser.getResult(); console.log('Result from User-Agent:', JSON.stringify(result1, null, 2)); // Example 2: Parsing with Client Hints (Node.js environment usually) // In a real application, these headers would come from an incoming HTTP request. const clientHintsHeaders = { 'sec-ch-ua': '"Chromium";v="124", "Google Chrome";v="124", "Not-A.Brand";v="99"', 'sec-ch-ua-mobile': '?0', 'sec-ch-ua-platform': '"macOS"', 'sec-ch-ua-platform-version': '"14.4.1"', 'sec-ch-ua-model': '', 'sec-ch-ua-arch': '"arm"' }; // Note: Headers must be an instance of `Headers` or compatible object for `withClientHints`. // In Node.js, this might involve converting `http.IncomingHttpHeaders`. const headersInstance = new Headers(clientHintsHeaders as any); // Type assertion for demo simplicity const parserWithClientHints = new UAParser(userAgentString) .withClientHints(headersInstance) .getResult(); console.log('\nResult from Client Hints:', JSON.stringify(parserWithClientHints, null, 2)); // Example 3: Using a submodule like bot-detection import { isBot } from 'ua-parser-js/extensions/bot-detection'; const botUserAgent = 'Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)'; const isGoogleBot = isBot(botUserAgent); console.log(`\nIs '${botUserAgent}' a bot? ${isGoogleBot}`);

Debug

Known issues

breakingStarting with version 2.0.0, ua-parser-js changed its license from MIT to AGPL-3.0. This is a significant change with strong implications for commercial and proprietary software usage. Ensure your project's license is compatible with AGPL-3.0 before upgrading or integrating version 2.x and beyond.

fix

Review your project's licensing model. If AGPL-3.0 is incompatible, consider remaining on version 1.x (which is MIT licensed) or exploring alternative libraries. Consult legal counsel for specific compliance advice.

affects: >=2.0.0

breakingMajor API changes occurred between version 1.x (and 0.7.x) and version 2.x. While the core `UAParser` class remains, specific methods, property names, and the overall structure of the returned result object (`IResult`) may have changed. Always consult the official documentation for version 2.x.

fix

Before upgrading, carefully read the `CHANGELOG.md` file and the official version 2.x documentation at `https://docs.uaparser.dev` to understand all breaking changes and adjust your code accordingly.

affects: >=2.0.0

gotchaUtilizing Client Hints for device detection requires server-side integration. The browser sends Client Hint headers to the server, which then need to be passed to `UAParser` using the `withClientHints(headers)` method. If Client Hints headers are not correctly captured and forwarded from the HTTP request, `UAParser` will only rely on the User-Agent string, potentially leading to less accurate or incomplete device information.

fix

Ensure your server-side application is configured to receive and forward Client Hint headers (e.g., `Sec-CH-UA`, `Sec-CH-UA-Platform`, etc.) from incoming requests to the `withClientHints()` method. In Node.js, this typically involves converting `http.IncomingHttpHeaders` to a `Headers` object.

affects: >=2.0.0

gotchaWhen using `ua-parser-js` in a browser environment, be aware that `navigator.userAgent` might be frozen or overridden by browser extensions, leading to unexpected results. Additionally, `withClientHints()` may not function as expected without server-side context.

fix

For client-side detection, always test thoroughly across different browsers and extensions. For more reliable and comprehensive detection, especially with Client Hints, consider performing parsing on the server-side where the raw HTTP headers are available and less prone to client-side manipulation.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: UAParser is not a constructor

Attempting to instantiate `UAParser` as a named export (`import { UAParser } from 'ua-parser-js';`) or incorrectly via CommonJS `require` when it is the default export.

fix

For ESM, use `import UAParser from 'ua-parser-js';`. For CommonJS, use `const UAParser = require('ua-parser-js');`.

TypeError: Cannot read properties of undefined (reading 'browser') or similar property access error on result object

Accessing properties on the result object (`IResult`) before ensuring the `UAParser` instance has been initialized with a valid user-agent or `getResult()` has been called.

fix

Ensure you call `const parser = new UAParser(userAgentString);` with a string (or let it default to `navigator.userAgent` in browser) and then `const result = parser.getResult();` before trying to access `result.browser`, `result.os`, etc.

TS2307: Cannot find module 'ua-parser-js/extensions/bot-detection' or its corresponding type declarations.

Incorrect import path for submodule utilities or missing type declarations for specific submodules.

fix

Verify the exact import path for the submodule (e.g., `ua-parser-js/extensions/bot-detection`). Ensure TypeScript is configured correctly to resolve module paths and that `ua-parser-js` is installed with its types, which are shipped with the package.

Upgrade

Version history

2.0.9latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/faisalman/ua-parser-js ↗

packagehttps://www.npmjs.com/package/ua-parser-js ↗

homepagehttps://uaparser.dev ↗