esbuild-plugin-es5

2.1.1 verified Mon Apr 27 auth: no javascript

An esbuild plugin that uses @swc/core to transform JavaScript/TypeScript to ES5, enabling compatibility with older browsers and devices. Version 2.1.1 supports tree shaking, code sharing (async generators), source maps, custom swc options, and custom filter. It is a peer dependency of esbuild and requires @swc/helpers at runtime. Compared to alternatives like Babel-based plugins, it leverages the faster SWC transform, though it adds ~130ms overhead (e.g., three.js build from 50ms to 180ms). The plugin is actively maintained with TypeScript types included. Use in production builds only, as development can use esbuild's native targets for speed.

Common errors

error Cannot find module '@swc/helpers' ↓

cause @swc/helpers not installed or alias misconfigured.

fix

Run npm install @swc/helpers -D and add the alias configuration shown in Quickstart.

error TypeError: es5Plugin is not a function ↓

cause Importing default instead of named export in version 2.x.

fix

Use import { es5Plugin } from 'esbuild-plugin-es5'.

error Error: The plugin 'es5Plugin' returned a 'name' property that is not a string. ↓

cause Outdated version of esbuild not compatible with plugin's return format.

fix

Update esbuild to latest stable version (>=0.14.0).

error warnings: [ {"text":"Top-level 'this' is replaced..."} ] ↓

cause SWC transform may produce warnings about 'this' outside functions.

fix

These are non-blocking; suppress via esbuild's logLevel or logOverride.

Warnings

deprecated The package uses @swc/core which has major version changes; verify compatibility with peerdep esbuild. ↓

fix Ensure @swc/core and @swc/helpers are updated to compatible versions.

gotcha Must set alias for @swc/helpers to relative path of @swc/helpers/package.json; otherwise SWC fails to resolve helpers at runtime. ↓

fix Add alias as shown in Quickstart: '@swc/helpers': path.dirname(require.resolve('@swc/helpers/package.json'))

breaking Version 2.x changed the default export to named export 'es5Plugin'. Old 'default' import breaks. ↓

fix Use `import { es5Plugin } from 'esbuild-plugin-es5'` instead of `import es5Plugin from ...`

gotcha Plugin only transforms code that passes the default filter (JS/TS extensions). If using custom extensions, must specify filter. ↓

fix Provide `filter` option: `es5Plugin({ filter: /\.m?[jt]sx?$/ })`

deprecated The package name in npm is 'esbuild-plugin-es5' but the repository and README may reference 'esbuild-build-es5' (typo). ↓

fix Install via npm using 'esbuild-plugin-es5'.

Install

npm install esbuild-plugin-es5

yarn add esbuild-plugin-es5

pnpm add esbuild-plugin-es5

Imports

es5Plugin
wrong
```
const es5Plugin = require('esbuild-plugin-es5').es5Plugin
```
correct
```
import { es5Plugin } from 'esbuild-plugin-es5'
```
Package is ESM-first. If using CommonJS, use dynamic import or named require after transpilation.

Es5Plugin

wrong

import { Es5Plugin } from 'esbuild-plugin-es5' (if used as value, not type)

correct

import type { Es5Plugin } from 'esbuild-plugin-es5'

Es5Plugin is a TypeScript type for the plugin instance; not a runtime value.

SWCOptions

wrong

import { SWCOptions } from 'esbuild-plugin-es5' (same type-only caution)

correct

import type { SWCOptions } from 'esbuild-plugin-es5'

SWCOptions is a possibly exported type; verify via your IDE.

Quickstart

Shows how to configure esbuild with esbuild-plugin-es5: import plugin, set target to 'es5', and alias @swc/helpers for correct resolution.

import { es5Plugin } from 'esbuild-plugin-es5';
import path from 'path';

await require('esbuild').build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/index.js',
  plugins: [es5Plugin()],
  target: ['es5'],
  alias: {
    '@swc/helpers': path.dirname(require.resolve('@swc/helpers/package.json')),
  },
});