{"id":25321,"library":"esbuild-plugin-browserslist","title":"esbuild-plugin-browserslist","description":"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.","status":"active","version":"3.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/nihalgonsalves/esbuild-plugin-browserslist","tags":["javascript","typescript"],"install":[{"cmd":"npm install esbuild-plugin-browserslist","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-browserslist","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-browserslist","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency: esbuild ~0.28.0 required to use the plugin","package":"esbuild","optional":false},{"reason":"Peer dependency: browserslist ^4.28.2 required to resolve browser queries","package":"browserslist","optional":false}],"imports":[{"note":"ESM-only since v1.0.0; require() works only in Node >=20.19.0 with --experimental-require-module","wrong":"const esbuildPluginBrowserslist = require('esbuild-plugin-browserslist')","symbol":"esbuildPluginBrowserslist","correct":"import { esbuildPluginBrowserslist } from 'esbuild-plugin-browserslist'"},{"note":"Named export, not default export. Use named import or destructured require.","wrong":"import resolveToEsbuildTarget from 'esbuild-plugin-browserslist'","symbol":"resolveToEsbuildTarget","correct":"import { resolveToEsbuildTarget } from 'esbuild-plugin-browserslist'"},{"note":"The package has a default export (the plugin function) that can be imported directly. In older Node versions, using require() and .default is incorrect.","wrong":"const plugin = require('esbuild-plugin-browserslist').default","symbol":"default import","correct":"import plugin from 'esbuild-plugin-browserslist'"}],"quickstart":{"code":"import esbuild from 'esbuild';\nimport browserslist from 'browserslist';\nimport { esbuildPluginBrowserslist } from 'esbuild-plugin-browserslist';\n\nawait esbuild.build({\n  entryPoints: ['./app.ts'],\n  bundle: true,\n  outfile: 'out.js',\n  plugins: [\n    esbuildPluginBrowserslist(browserslist('> 0.5%, last 2 versions, Firefox ESR, not dead'), {\n      printUnknownTargets: false,\n    }),\n  ],\n});","lang":"typescript","description":"Basic usage: pass browserslist query to the plugin and use it in esbuild's build step."},"warnings":[{"fix":"Upgrade to Node >=20.19.0 or use ESM imports. For older Node, stick with v0.x.","message":"Version 1.0.0 dropped Node 18 support and is now pure ESM. CJS require() may fail on older Node versions.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Install esbuild@0.28.x alongside the plugin.","message":"Peer dependency esbuild must be ~0.28.0 for v3.x. Using incompatible esbuild version will cause runtime errors.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update browserslist to ^4.28.2.","message":"Peer dependency browserslist must be ^4.28.2 for v3.x. Older browserslist versions may not work.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Use printUnknownTargets: true to see warnings for unmapped browsers.","message":"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.","severity":"gotcha","affected_versions":"*"},{"fix":"Do not set 'target' in esbuild.build options when using the plugin.","message":"The plugin sets the esbuild 'target' option. If you also set 'target' manually in the build options, behavior is undefined.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Add \"type\": \"module\" to package.json or use dynamic import().","cause":"Using ESM import syntax in a CommonJS project without configuring 'type': 'module'.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Use import instead, or upgrade Node to >=20.19.0 and use --experimental-require-module.","cause":"Calling require() on the ESM-only package in Node versions that don't support require(esm).","error":"ERR_REQUIRE_ESM: require() of ES Module /node_modules/esbuild-plugin-browserslist/build/index.mjs not supported"},{"fix":"Check the browserslist query or set printUnknownTargets: true to see which browsers are unmapped.","cause":"The browserslist query resolved to a browser version that esbuild does not recognize.","error":"Plugin esbuildPluginBrowserslist: Invalid target: ..."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}