{"id":10595,"library":"browserslist-useragent-regexp","title":"Browserslist Useragent Regexp","description":"browserslist-useragent-regexp is a utility that compiles a `browserslist` query into a JavaScript regular expression, enabling client-side user agent detection. This allows developers to determine if a browser supports a given `browserslist` configuration directly in the browser, without server-side checks. It is currently at version 4.1.4 and receives active maintenance, with frequent bug fixes and minor feature releases. Key differentiators include its direct integration with `browserslist` for consistent browser targeting across toolchains and its ability to generate optimized regex patterns. Since version 4.0.0, it is an ESM-only package and requires Node.js >= 14. This library is particularly useful for conditional loading of polyfills or different JavaScript bundles based on client-side browser capabilities.","status":"active","version":"4.1.4","language":"javascript","source_language":"en","source_url":"https://github.com/browserslist/browserslist-useragent-regexp","tags":["javascript","browserslist","useragent","regexp","typescript"],"install":[{"cmd":"npm install browserslist-useragent-regexp","lang":"bash","label":"npm"},{"cmd":"yarn add browserslist-useragent-regexp","lang":"bash","label":"yarn"},{"cmd":"pnpm add browserslist-useragent-regexp","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency since v4.0.0 to resolve browser queries.","package":"browserslist","optional":false}],"imports":[{"note":"The package is ESM-only since v4.0.0. The primary function to programmatically generate the regex is `browserslistUseragentRegexp`.","wrong":"const browserslistUseragentRegexp = require('browserslist-useragent-regexp');","symbol":"browserslistUseragentRegexp","correct":"import { browserslistUseragentRegexp } from 'browserslist-useragent-regexp';"},{"note":"A common usage pattern is to use the `browserslist-useragent-regexp` CLI to generate a JavaScript file (e.g., `supportedBrowsers.js`) that exports the compiled RegExp as a default export.","symbol":"RegExp from generated file","correct":"import supportedBrowsersRegex from './supportedBrowsers.js';"},{"note":"TypeScript types are shipped with the package for its programmatic API, allowing for type-safe usage of the options object.","symbol":"Type for function options","correct":"import type { Options } from 'browserslist-useragent-regexp';"}],"quickstart":{"code":"/* .browserslistrc */\n// last 2 versions\n// not dead\n\n/* package.json */\n// {\n//   \"scripts\": {\n//     \"generate-regex\": \"echo \\\"export default $(browserslist-useragent-regexp --allowHigherVersions);\\\" > supportedBrowsers.js\"\n//   }\n// }\n\n// Run in your terminal once:\n// npm run generate-regex\n\n// --- supportedBrowsers.js (generated) ---\n// export default /Edge?\\/(10[5-9]|1[1-9]\\d|[2-9]\\d\\d|...)/; /* (actual regex will vary) */\n\n// --- your-app.js ---\nimport supportedBrowsersRegex from './supportedBrowsers.js';\n\nfunction checkBrowserSupport() {\n  const userAgent = typeof navigator !== 'undefined' ? navigator.userAgent : process.env.USER_AGENT ?? '';\n  if (userAgent === '') {\n    console.warn('User-Agent string is empty. Cannot perform check.');\n    return;\n  }\n\n  if (supportedBrowsersRegex.test(userAgent)) {\n    console.log(`User agent '${userAgent}' is supported.`);\n  } else {\n    console.warn(`User agent '${userAgent}' is NOT supported.`);\n  }\n}\n\n// Example usage (replace with actual user agent for testing)\nprocess.env.USER_AGENT = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36';\ncheckBrowserSupport();\n\nprocess.env.USER_AGENT = 'Mozilla/5.0 (Windows NT 6.1; Trident/7.0; rv:11.0) like Gecko'; // IE 11 (likely unsupported)\ncheckBrowserSupport();\n","lang":"typescript","description":"This quickstart demonstrates the common pattern of using the CLI to generate a JavaScript file containing the compiled RegExp, which is then imported and used to test a user agent string. It includes setup for the `.browserslistrc` and a `package.json` script, along with example runtime usage."},"warnings":[{"fix":"Migrate your import statements to use ES module syntax (e.g., `import ... from 'package';`). Ensure your project is configured for ESM, potentially by adding `\"type\": \"module\"` to `package.json` or using `.mjs` file extensions.","message":"The package moved to ESM-only and dropped CommonJS support. Attempting to `require()` the package will result in an `ERR_REQUIRE_ESM` error.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure `browserslist` is installed as a dependency in your project: `npm install browserslist` or `pnpm add browserslist`.","message":"`browserslist` is no longer a direct dependency but a peer dependency. It must be installed separately in your project.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade your Node.js environment to version 14 or higher.","message":"The minimum required Node.js version was bumped to 14. Projects running on older Node.js versions will encounter compatibility issues.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Review your programmatic usage of the library and update any references from `regexp` to `regex` in option keys or properties.","message":"Naming conventions within the JavaScript API changed from `regexp` to `regex`. If you were programmatically using properties or options with `regexp` in their name, they are now `regex`.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade your Node.js environment to version 12 or higher.","message":"The minimum required Node.js version was bumped to 12.","severity":"breaking","affected_versions":">=3.0.0 <4.0.0"},{"fix":"Pass a `browsers` array to the `browserslistUseragentRegexp` function options or ensure a valid `.browserslistrc` file is in your project's root or configured location.","message":"When using the programmatic API (`browserslistUseragentRegexp`), you must either specify `browsers` in the options object or have a `.browserslistrc` file present in your project, otherwise, the `browserslist` query resolution will fail.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const someVar = require('browserslist-useragent-regexp');` to `import { someVar } from 'browserslist-useragent-regexp';`. Ensure your project's `package.json` has `\"type\": \"module\"` or use `.mjs` file extensions for ESM files.","cause":"Attempting to import an ESM-only package using CommonJS `require()` syntax.","error":"Error [ERR_REQUIRE_ESM]: require() of ES module 'browserslist-useragent-regexp' from ... not supported."},{"fix":"Provide a `browsers` array in the options object (e.g., `browserslistUseragentRegexp({ browsers: ['last 2 versions'] })`) or ensure a `.browserslistrc` file is correctly configured in your project.","cause":"The `browserslistUseragentRegexp` function was called without providing a `browsers` array in its options or without a resolvable `.browserslistrc` configuration.","error":"TypeError: The 'browsers' option is required."},{"fix":"Install `browserslist` in your project: `npm install browserslist` or `pnpm add browserslist`.","cause":"The `browserslist` package, a peer dependency since v4.0.0, is not installed in the project.","error":"Error: Cannot find package 'browserslist'. Did you mean to install it?"}],"ecosystem":"npm"}