esbuild-plugin-browserslist

3.0.2 verified Fri May 01 auth: no javascript

An esbuild plugin that automatically configures the esbuild `target` option based on a browserslist query. Current stable version is 3.0.2 (released April 2026), previously v2.0.0 (November 2025). Requires esbuild ~0.28.0 and browserslist ^4.28.2 as peer dependencies. Unlike manually specifying esbuild targets, this plugin resolves browserslist queries (e.g., "defaults") into esbuild-compatible browser versions, mapping browsers like Chrome, Firefox, Safari, Edge, iOS Safari, and Node. Unknown browser targets are warned via `printUnknownTargets` option. Ships with TypeScript definitions. Pure ESM package requires Node >=20.19.0 or appropriate module resolution.

Common errors

error SyntaxError: Cannot use import statement outside a module ↓

cause Using ESM import syntax in a CommonJS project without configuring 'type': 'module'.

fix

Add "type": "module" to package.json or use dynamic import().

error ERR_REQUIRE_ESM: require() of ES Module /node_modules/esbuild-plugin-browserslist/build/index.mjs not supported ↓

cause Calling require() on the ESM-only package in Node versions that don't support require(esm).

fix

Use import instead, or upgrade Node to >=20.19.0 and use --experimental-require-module.

error Plugin esbuildPluginBrowserslist: Invalid target: ... ↓

cause The browserslist query resolved to a browser version that esbuild does not recognize.

fix

Check the browserslist query or set printUnknownTargets: true to see which browsers are unmapped.

Warnings

breaking Version 1.0.0 dropped Node 18 support and is now pure ESM. CJS require() may fail on older Node versions. ↓

fix Upgrade to Node >=20.19.0 or use ESM imports. For older Node, stick with v0.x.

breaking Peer dependency esbuild must be ~0.28.0 for v3.x. Using incompatible esbuild version will cause runtime errors. ↓

fix Install esbuild@0.28.x alongside the plugin.

breaking Peer dependency browserslist must be ^4.28.2 for v3.x. Older browserslist versions may not work. ↓

fix Update browserslist to ^4.28.2.

gotcha Only a subset of browsers are mapped to esbuild targets (edge, firefox, chrome, safari, ios_saf, node). Others (e.g., samsung, opera, ie) are silently ignored. ↓

fix Use printUnknownTargets: true to see warnings for unmapped browsers.

gotcha The plugin sets the esbuild 'target' option. If you also set 'target' manually in the build options, behavior is undefined. ↓

fix Do not set 'target' in esbuild.build options when using the plugin.

Install

npm install esbuild-plugin-browserslist

yarn add esbuild-plugin-browserslist

pnpm add esbuild-plugin-browserslist

Imports

esbuildPluginBrowserslist

wrong

const esbuildPluginBrowserslist = require('esbuild-plugin-browserslist')

correct

import { esbuildPluginBrowserslist } from 'esbuild-plugin-browserslist'

ESM-only since v1.0.0; require() works only in Node >=20.19.0 with --experimental-require-module

resolveToEsbuildTarget

wrong

import resolveToEsbuildTarget from 'esbuild-plugin-browserslist'

correct

import { resolveToEsbuildTarget } from 'esbuild-plugin-browserslist'

Named export, not default export. Use named import or destructured require.

default import
wrong
```
const plugin = require('esbuild-plugin-browserslist').default
```
correct
```
import plugin from 'esbuild-plugin-browserslist'
```
The package has a default export (the plugin function) that can be imported directly. In older Node versions, using require() and .default is incorrect.

Quickstart

Basic usage: pass browserslist query to the plugin and use it in esbuild's build step.

import esbuild from 'esbuild';
import browserslist from 'browserslist';
import { esbuildPluginBrowserslist } from 'esbuild-plugin-browserslist';

await esbuild.build({
  entryPoints: ['./app.ts'],
  bundle: true,
  outfile: 'out.js',
  plugins: [
    esbuildPluginBrowserslist(browserslist('> 0.5%, last 2 versions, Firefox ESR, not dead'), {
      printUnknownTargets: false,
    }),
  ],
});