{"id":16256,"library":"ua-parser-js","title":"UAParser.js: User-Agent & Client Hints Parser","description":"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.","status":"active","version":"2.0.9","language":"javascript","source_language":"en","source_url":"https://github.com/faisalman/ua-parser-js","tags":["javascript","user-agent","client-hints","browser","engine","os","device","cpu","ua-parser-js","typescript"],"install":[{"cmd":"npm install ua-parser-js","lang":"bash","label":"npm"},{"cmd":"yarn add ua-parser-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add ua-parser-js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The UAParser class is exported as the default export since version 2.x. For CommonJS, use `const UAParser = require('ua-parser-js');`.","wrong":"import { UAParser } from 'ua-parser-js';","symbol":"UAParser","correct":"import UAParser from 'ua-parser-js';"},{"note":"Import TypeScript types separately for type safety.","symbol":"IResult","correct":"import type { IResult } from 'ua-parser-js';"},{"note":"Utility functions like `isBot` are part of specific submodules under `extensions` and must be imported from their dedicated paths.","wrong":"import { isBot } from 'ua-parser-js';","symbol":"isBot","correct":"import { isBot } from 'ua-parser-js/extensions/bot-detection';"},{"note":"This is the correct CommonJS `require` syntax for the default export. Mixing this with ESM `import` in hybrid environments can lead to issues.","symbol":"UAParser CommonJS","correct":"const UAParser = require('ua-parser-js');"}],"quickstart":{"code":"import UAParser from 'ua-parser-js';\nimport type { IResult } from 'ua-parser-js';\n\n// Example 1: Parsing a standard User-Agent string\nconst 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';\nconst parser = new UAParser(userAgentString);\nconst result1: IResult = parser.getResult();\nconsole.log('Result from User-Agent:', JSON.stringify(result1, null, 2));\n\n// Example 2: Parsing with Client Hints (Node.js environment usually)\n// In a real application, these headers would come from an incoming HTTP request.\nconst clientHintsHeaders = {\n  'sec-ch-ua': '\"Chromium\";v=\"124\", \"Google Chrome\";v=\"124\", \"Not-A.Brand\";v=\"99\"',\n  'sec-ch-ua-mobile': '?0',\n  'sec-ch-ua-platform': '\"macOS\"',\n  'sec-ch-ua-platform-version': '\"14.4.1\"',\n  'sec-ch-ua-model': '',\n  'sec-ch-ua-arch': '\"arm\"'\n};\n\n// Note: Headers must be an instance of `Headers` or compatible object for `withClientHints`.\n// In Node.js, this might involve converting `http.IncomingHttpHeaders`.\nconst headersInstance = new Headers(clientHintsHeaders as any); // Type assertion for demo simplicity\n\nconst parserWithClientHints = new UAParser(userAgentString)\n  .withClientHints(headersInstance)\n  .getResult();\n\nconsole.log('\\nResult from Client Hints:', JSON.stringify(parserWithClientHints, null, 2));\n\n// Example 3: Using a submodule like bot-detection\nimport { isBot } from 'ua-parser-js/extensions/bot-detection';\n\nconst botUserAgent = 'Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)';\nconst isGoogleBot = isBot(botUserAgent);\nconsole.log(`\\nIs '${botUserAgent}' a bot? ${isGoogleBot}`);","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Starting 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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"Major 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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"Utilizing 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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"For ESM, use `import UAParser from 'ua-parser-js';`. For CommonJS, use `const UAParser = require('ua-parser-js');`.","cause":"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.","error":"TypeError: UAParser is not a constructor"},{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'browser') or similar property access error on result object"},{"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.","cause":"Incorrect import path for submodule utilities or missing type declarations for specific submodules.","error":"TS2307: Cannot find module 'ua-parser-js/extensions/bot-detection' or its corresponding type declarations."}],"ecosystem":"npm"}