Registry / http-networking / browserslist-useragent

browserslist-useragent

library4.0.0jsnpmunverified

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.

http-networking testing

npm install browserslist-useragent

github ↗package ↗

INSTALL

IMPORT

SIG · BROWSERSLIST-USERA

browserslist-useragent

http-networkingjavascriptv4.0.0

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.

matchesUA

✓ import { matchesUA } from 'browserslist-useragent';

✗ import matchesUA from 'browserslist-useragent';

The primary function `matchesUA` is a named export. For CommonJS, use `const { matchesUA} = require('browserslist-useragent');`

BrowserslistUseragentOptions

✓ import type { BrowserslistUseragentOptions } from 'browserslist-useragent';

Type import for configuration options when using TypeScript.

matchesUA (CommonJS)

✓ const { matchesUA } = require('browserslist-useragent');

✗ const matchesUA = require('browserslist-useragent'); // Missing destructuring for named export

While v4 is TypeScript, CommonJS `require` is still supported for JavaScript projects. Ensure destructuring is used for named exports.

Demonstrates matching a user agent against inferred browserslist config, explicit queries, and utilizing options like `allowHigherVersions`.

import { matchesUA, BrowserslistUseragentOptions } from 'browserslist-useragent'; // Example .browserslistrc (or in package.json): // > 0.2% // not dead // Chrome >= 90 const 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'; const oldFirefoxUA: string = 'Mozilla/5.0 (Windows NT 6.1; WOW64; rv:31.0) Gecko/20130401 Firefox/31.0'; // 1. Match against project's browserslist config (e.g., in .browserslistrc) const matchesModernChrome: boolean = matchesUA(modernChromeUA); console.log(`Does modern Chrome UA match project config? ${matchesModernChrome}`); // 2. Match against an explicitly provided browserslist query const explicitOptions: BrowserslistUseragentOptions = { browsers: ['last 2 Chrome versions', 'last 2 Firefox versions'] }; const matchesExplicitQuery: boolean = matchesUA(modernChromeUA, explicitOptions); console.log(`Does modern Chrome UA match 'last 2 Chrome/Firefox versions'? ${matchesExplicitQuery}`); // 3. Using additional options: allowHigherVersions const browserlistQuery: string[] = ['Firefox >= 50']; const firefoxUA_v54: string = 'Mozilla/5.0 (Windows NT 10.0; rv:54.0) Gecko/20100101 Firefox/54.0'; const matchesFirefoxStrict: boolean = matchesUA(firefoxUA_v54, { browsers: browserlistQuery }); console.log(`Firefox 54 matches 'Firefox >= 50' (strict)? ${matchesFirefoxStrict}`); const matchesFirefoxAllowHigher: boolean = matchesUA(firefoxUA_v54, { browsers: ['Firefox 50'], allowHigherVersions: true }); console.log(`Firefox 54 matches 'Firefox 50' (allowHigherVersions)? ${matchesFirefoxAllowHigher}`);

Debug

Known issues

breakingVersion 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.

fix

Thoroughly test user agent matching logic after upgrading to v4.0.0 to ensure consistent behavior with `ua-parser-js`.

affects: >=4.0.0

breakingNode.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.

fix

Upgrade your Node.js runtime to version 14 or higher.

affects: >=4.0.0

breaking`browserslist` is now explicitly a peer dependency. If not already installed, it must be installed in your project alongside `browserslist-useragent`.

fix

Install `browserslist` in your project: `npm install browserslist` or `yarn add browserslist`.

affects: >=4.0.0

gotchaPrior 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.

fix

Upgrade to `browserslist-useragent` v4.0.0 or newer to benefit from an actively maintained user agent parsing library (`ua-parser-js`).

affects: <4.0.0

gotchaOlder versions (pre-v3.0.3) had an issue where `allowHigherVersions` combined with `unreleased Safari versions` in the browserslist could lead to incorrect matches.

fix

Ensure you are using `browserslist-useragent` v3.0.3 or higher if relying on `allowHigherVersions` with Safari browser queries.

affects: <3.0.3

Errors

Common errors & fixes

Error: Cannot find module 'browserslist'

The `browserslist` package is a peer dependency but is not installed in the project.

fix

Install the `browserslist` package: `npm install browserslist` or `yarn add browserslist`.

ReferenceError: require is not defined in ES module scope

Attempting to use CommonJS `require()` syntax in an ECMAScript Module (ESM) environment without proper transpilation or configuration.

fix

For ESM projects, use `import { matchesUA } from 'browserslist-useragent';`. Ensure your project is configured for ESM if you intend to use it.

User agent string unexpectedly does not match any browsers

Incorrect `browsers` option, `ignorePatch`/`ignoreMinor` settings, or `allowHigherVersions` misconfiguration preventing a match for a seemingly compatible user agent.

fix

Review the `options` object passed to `matchesUA`. Pay close attention to `browsers` (ensuring it's an array of strings), `ignorePatch`, `ignoreMinor`, and `allowHigherVersions`.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

browserslistrequiredRequired peer dependency to define browser targets.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/pastelsky/browserslist-useragent ↗

packagehttps://www.npmjs.com/package/browserslist-useragent ↗