{"id":12913,"library":"browserslist-useragent","title":"Browserslist Useragent Matcher","description":"browserslist-useragent is a utility library designed to determine if a given browser user agent string satisfies a specified browserslist query. The current stable version, 4.0.0, marks a significant rewrite in TypeScript and a switch from the 'useragent' parsing library to 'ua-parser-js', which may introduce subtle differences in how user agents are classified. This library seamlessly integrates with existing browserslist configurations found in project files like `.browserslistrc` or `package.json`, but also provides options for explicitly defining browser queries. It supports a comprehensive range of popular browsers, including Chrome, Firefox, Safari, Edge, and Internet Explorer, offering granular control over version matching through options like ignoring patch or minor versions, or allowing higher versions than specified. While there isn't a fixed release cadence, updates are regularly issued to incorporate bug fixes, add support for new browsers, and improve the underlying parsing logic.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/pastelsky/browserslist-useragent","tags":["javascript"],"install":[{"cmd":"npm install browserslist-useragent","lang":"bash","label":"npm"},{"cmd":"yarn add browserslist-useragent","lang":"bash","label":"yarn"},{"cmd":"pnpm add browserslist-useragent","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency to define browser targets.","package":"browserslist","optional":false}],"imports":[{"note":"The primary function `matchesUA` is a named export. For CommonJS, use `const { matchesUA} = require('browserslist-useragent');`","wrong":"import matchesUA from 'browserslist-useragent';","symbol":"matchesUA","correct":"import { matchesUA } from 'browserslist-useragent';"},{"note":"Type import for configuration options when using TypeScript.","symbol":"BrowserslistUseragentOptions","correct":"import type { BrowserslistUseragentOptions } from 'browserslist-useragent';"},{"note":"While v4 is TypeScript, CommonJS `require` is still supported for JavaScript projects. Ensure destructuring is used for named exports.","wrong":"const matchesUA = require('browserslist-useragent'); // Missing destructuring for named export","symbol":"matchesUA (CommonJS)","correct":"const { matchesUA } = require('browserslist-useragent');"}],"quickstart":{"code":"import { matchesUA, BrowserslistUseragentOptions } from 'browserslist-useragent';\n\n// Example .browserslistrc (or in package.json):\n// > 0.2%\n// not dead\n// Chrome >= 90\n\nconst modernChromeUA: string = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.88 Safari/537.36';\nconst oldFirefoxUA: string = 'Mozilla/5.0 (Windows NT 6.1; WOW64; rv:31.0) Gecko/20130401 Firefox/31.0';\n\n// 1. Match against project's browserslist config (e.g., in .browserslistrc)\nconst matchesModernChrome: boolean = matchesUA(modernChromeUA);\nconsole.log(`Does modern Chrome UA match project config? ${matchesModernChrome}`);\n\n// 2. Match against an explicitly provided browserslist query\nconst explicitOptions: BrowserslistUseragentOptions = { browsers: ['last 2 Chrome versions', 'last 2 Firefox versions'] };\nconst matchesExplicitQuery: boolean = matchesUA(modernChromeUA, explicitOptions);\nconsole.log(`Does modern Chrome UA match 'last 2 Chrome/Firefox versions'? ${matchesExplicitQuery}`);\n\n// 3. Using additional options: allowHigherVersions\nconst browserlistQuery: string[] = ['Firefox >= 50'];\nconst firefoxUA_v54: string = 'Mozilla/5.0 (Windows NT 10.0; rv:54.0) Gecko/20100101 Firefox/54.0';\nconst matchesFirefoxStrict: boolean = matchesUA(firefoxUA_v54, { browsers: browserlistQuery });\nconsole.log(`Firefox 54 matches 'Firefox >= 50' (strict)? ${matchesFirefoxStrict}`);\n\nconst matchesFirefoxAllowHigher: boolean = matchesUA(firefoxUA_v54, {\n  browsers: ['Firefox 50'],\n  allowHigherVersions: true\n});\nconsole.log(`Firefox 54 matches 'Firefox 50' (allowHigherVersions)? ${matchesFirefoxAllowHigher}`);\n","lang":"typescript","description":"Demonstrates matching a user agent against inferred browserslist config, explicit queries, and utilizing options like `allowHigherVersions`."},"warnings":[{"fix":"Thoroughly test user agent matching logic after upgrading to v4.0.0 to ensure consistent behavior with `ua-parser-js`.","message":"Version 4.0.0 replaced the underlying `useragent` parsing library with `ua-parser-js`. This change might introduce minor differences in how user agents are classified and parsed, potentially affecting match results.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade your Node.js runtime to version 14 or higher.","message":"Node.js versions older than v14 are no longer supported starting with v4.0.0. Users on older Node.js environments must upgrade their Node.js version.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Install `browserslist` in your project: `npm install browserslist` or `yarn add browserslist`.","message":"`browserslist` is now explicitly a peer dependency. If not already installed, it must be installed in your project alongside `browserslist-useragent`.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade to `browserslist-useragent` v4.0.0 or newer to benefit from an actively maintained user agent parsing library (`ua-parser-js`).","message":"Prior to v4.0.0, the library relied on the `useragent` package, which was noted as unmaintained (as of v3.1.1). While this was addressed in v4, older versions might use outdated parsing definitions.","severity":"gotcha","affected_versions":"<4.0.0"},{"fix":"Ensure you are using `browserslist-useragent` v3.0.3 or higher if relying on `allowHigherVersions` with Safari browser queries.","message":"Older versions (pre-v3.0.3) had an issue where `allowHigherVersions` combined with `unreleased Safari versions` in the browserslist could lead to incorrect matches.","severity":"gotcha","affected_versions":"<3.0.3"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install the `browserslist` package: `npm install browserslist` or `yarn add browserslist`.","cause":"The `browserslist` package is a peer dependency but is not installed in the project.","error":"Error: Cannot find module 'browserslist'"},{"fix":"For ESM projects, use `import { matchesUA } from 'browserslist-useragent';`. Ensure your project is configured for ESM if you intend to use it.","cause":"Attempting to use CommonJS `require()` syntax in an ECMAScript Module (ESM) environment without proper transpilation or configuration.","error":"ReferenceError: require is not defined in ES module scope"},{"fix":"Review the `options` object passed to `matchesUA`. Pay close attention to `browsers` (ensuring it's an array of strings), `ignorePatch`, `ignoreMinor`, and `allowHigherVersions`.","cause":"Incorrect `browsers` option, `ignorePatch`/`ignoreMinor` settings, or `allowHigherVersions` misconfiguration preventing a match for a seemingly compatible user agent.","error":"User agent string unexpectedly does not match any browsers"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}