vite-plugin-browserslist-useragent

0.7.0 verified Mon Apr 27 auth: no javascript

A Vite plugin that wraps browserslist-useragent-regexp to compile browserslist queries into RegExp patterns for testing browser user agents. Current stable version is 0.7.0, updated regularly. It automatically generates a virtual module (virtual:supported-browsers) that exposes the compiled regexes, eliminating the need to run CLI commands manually. Key differentiator: seamless integration with Vite's build pipeline, with support for Vite 3 through 8. Ships TypeScript definitions.

Common errors

error Error: Cannot find module 'virtual:supported-browsers' or its corresponding type declarations. ↓

cause TypeScript cannot resolve the virtual module without a declaration file.

fix

Create a .d.ts file (e.g., src/vite-env.d.ts) with: declare module 'virtual:supported-browsers' { export const browsersRegex: RegExp; export const browsersRegexes: any[]; }

error TypeError: Cannot destructure property 'browsersRegex' of '...' as it is undefined. ↓

cause Attempting named import from the plugin package instead of the virtual module.

fix

Use import SupportedBrowsers from 'vite-plugin-browserslist-useragent' for the plugin, and import { browsersRegex } from 'virtual:supported-browsers' for the regex.

error Error: Browserslist config not found. Create a .browserslistrc file or set browserslist in package.json. ↓

cause The plugin requires a browserslist configuration to generate regexes.

fix

Create a .browserslistrc file in the project root with your target browsers, e.g.: last 2 versions not dead

Warnings

gotcha The virtual module 'virtual:supported-browsers' is auto-generated and not a real file. TypeScript may complain about missing module declaration. ↓

fix Add a module declaration file: declare module 'virtual:supported-browsers' { export const browsersRegex: RegExp; export const browsersRegexes: Array<{family: string; regexString: string; requestVersionsStrings: string[]}>; }

gotcha Plugin options must be passed as object; omitting options uses defaults. Some options require specific browserslist-useragent-regexp version compatibility. ↓

fix Refer to the browserslist-useragent-regexp documentation for valid options. Example: SupportedBrowsers({ browsers: 'last 2 versions', env: 'production' })

gotcha The plugin depends on a browserslist configuration file (.browserslistrc) or a 'browserslist' key in package.json. Without it, no regexes may be generated. ↓

fix Create a .browserslistrc file in your project root with your desired browser queries (e.g., 'last 2 versions', 'not dead').

breaking Version 0.7.0 dropped support for Vite 2. Peer dependency now requires Vite ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0. ↓

fix Upgrade to Vite 3+ or stay on an older version of this plugin (<0.7.0) if using Vite 2.

Install

npm install vite-plugin-browserslist-useragent

yarn add vite-plugin-browserslist-useragent

pnpm add vite-plugin-browserslist-useragent

Imports

SupportedBrowsers

wrong

import { SupportedBrowsers } from 'vite-plugin-browserslist-useragent'

correct

import SupportedBrowsers from 'vite-plugin-browserslist-useragent'

Default export; named import will fail. TypeScript: use default import.

browsersRegex

wrong

import { browsersRegex } from 'vite-plugin-browserslist-useragent'

correct

import { browsersRegex } from 'virtual:supported-browsers'

Exposed via virtual module, not from the plugin package itself.

browsersRegexes

wrong

import { browsersRegexes } from 'vite-plugin-browserslist-useragent'

correct

import { browsersRegexes } from 'virtual:supported-browsers'

Also exposed via virtual module.

SupportedBrowsers

wrong

const { SupportedBrowsers } = require('vite-plugin-browserslist-useragent')

correct

const SupportedBrowsers = require('vite-plugin-browserslist-useragent')

CJS: default export via module.exports, not named export.

Quickstart

Shows how to install the plugin, add it to Vite config, and use the virtual module to test browser support via userAgent regex.

// vite.config.ts
import { defineConfig } from 'vite';
import SupportedBrowsers from 'vite-plugin-browserslist-useragent';

export default defineConfig({
  plugins: [SupportedBrowsers()],
});

// In your app code (e.g., main.ts)
import { browsersRegex } from 'virtual:supported-browsers';

const isSupported = browsersRegex.test(navigator.userAgent);
console.log('Browser supported:', isSupported);