Browserslist Useragent Regexp

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES module 'browserslist-useragent-regexp' from ... not supported.

  cause Attempting to import an ESM-only package using CommonJS `require()` syntax.
  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.

• TypeError: The 'browsers' option is required.

  cause The `browserslistUseragentRegexp` function was called without providing a `browsers` array in its options or without a resolvable `.browserslistrc` configuration.
  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.

• Error: Cannot find package 'browserslist'. Did you mean to install it?

  cause The `browserslist` package, a peer dependency since v4.0.0, is not installed in the project.
  fix Install `browserslist` in your project: `npm install browserslist` or `pnpm add browserslist`.

Warnings

• breaking The package moved to ESM-only and dropped CommonJS support. Attempting to `require()` the package will result in an `ERR_REQUIRE_ESM` error.
  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.
• breaking `browserslist` is no longer a direct dependency but a peer dependency. It must be installed separately in your project.
  Fix: Ensure `browserslist` is installed as a dependency in your project: `npm install browserslist` or `pnpm add browserslist`.
• breaking The minimum required Node.js version was bumped to 14. Projects running on older Node.js versions will encounter compatibility issues.
  Fix: Upgrade your Node.js environment to version 14 or higher.
• breaking 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`.
  Fix: Review your programmatic usage of the library and update any references from `regexp` to `regex` in option keys or properties.
• breaking The minimum required Node.js version was bumped to 12.
  Fix: Upgrade your Node.js environment to version 12 or higher.
• gotcha 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.
  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.

Install

• npm install browserslist-useragent-regexp npm
• yarn add browserslist-useragent-regexp yarn
• pnpm add browserslist-useragent-regexp pnpm

Imports

• browserslistUseragentRegexp
  wrong:

  const browserslistUseragentRegexp = require('browserslist-useragent-regexp');

  correct:

  import { browserslistUseragentRegexp } from 'browserslist-useragent-regexp';

  The package is ESM-only since v4.0.0. The primary function to programmatically generate the regex is `browserslistUseragentRegexp`.
• RegExp from generated file

  import supportedBrowsersRegex from './supportedBrowsers.js';

  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.
• Type for function options

  import type { Options } from 'browserslist-useragent-regexp';

  TypeScript types are shipped with the package for its programmatic API, allowing for type-safe usage of the options object.

Quickstart

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.

/* .browserslistrc */
// last 2 versions
// not dead

/* package.json */
// {
//   "scripts": {
//     "generate-regex": "echo \"export default $(browserslist-useragent-regexp --allowHigherVersions);\" > supportedBrowsers.js"
//   }
// }

// Run in your terminal once:
// npm run generate-regex

// --- supportedBrowsers.js (generated) ---
// export default /Edge?\/(10[5-9]|1[1-9]\d|[2-9]\d\d|...)/; /* (actual regex will vary) */

// --- your-app.js ---
import supportedBrowsersRegex from './supportedBrowsers.js';

function checkBrowserSupport() {
  const userAgent = typeof navigator !== 'undefined' ? navigator.userAgent : process.env.USER_AGENT ?? '';
  if (userAgent === '') {
    console.warn('User-Agent string is empty. Cannot perform check.');
    return;
  }

  if (supportedBrowsersRegex.test(userAgent)) {
    console.log(`User agent '${userAgent}' is supported.`);
  } else {
    console.warn(`User agent '${userAgent}' is NOT supported.`);
  }
}

// Example usage (replace with actual user agent for testing)
process.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';
checkBrowserSupport();

process.env.USER_AGENT = 'Mozilla/5.0 (Windows NT 6.1; Trident/7.0; rv:11.0) like Gecko'; // IE 11 (likely unsupported)
checkBrowserSupport();