Registry / devops / esbuild-plugin-browserslist

esbuild-plugin-browserslist

library3.0.2jsnpmunverified

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.

devops

npm install esbuild-plugin-browserslist

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-PLUGIN-BRO

esbuild-plugin-browserslist

devopsjavascriptv3.0.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

esbuildPluginBrowserslist

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

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

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

resolveToEsbuildTarget

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

✗ import resolveToEsbuildTarget from 'esbuild-plugin-browserslist'

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

default import

✓ import plugin from 'esbuild-plugin-browserslist'

✗ const plugin = require('esbuild-plugin-browserslist').default

The package has a default export (the plugin function) that can be imported directly. In older Node versions, using require() and .default is incorrect.

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, }), ], });

Debug

Known issues

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

affects: >=1.0.0

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

affects: >=3.0.0

breakingPeer dependency browserslist must be ^4.28.2 for v3.x. Older browserslist versions may not work.

fix

Update browserslist to ^4.28.2.

affects: >=3.0.0

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

affects: *

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

affects: *

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

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

fix

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

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

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.

Plugin esbuildPluginBrowserslist: Invalid target: ...

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.

Upgrade

Version history

3.0.2latest on npm

Audit

Dependencies

esbuildrequiredPeer dependency: esbuild ~0.28.0 required to use the plugin

browserslistrequiredPeer dependency: browserslist ^4.28.2 required to resolve browser queries

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/nihalgonsalves/esbuild-plugin-browserslist ↗

packagehttps://www.npmjs.com/package/esbuild-plugin-browserslist ↗