esbuild-plugin-babel-cjs

1.0.0 verified Fri May 01 auth: no javascript

A CommonJS-compatible Babel plugin for esbuild. Current stable version 1.0.0. This plugin allows you to apply Babel transformations within esbuild bundles when esbuild's native transform capabilities are insufficient. Unlike alternatives (e.g., esbuild-plugin-babel or @aspect-build/esbuild), this package explicitly targets CommonJS environments and provides a simple, minimal API. It requires @babel/core as a peer dependency and delegates Babel configuration to babel.config.json or inline config. Suitable for legacy projects or those locked into CJS.

Common errors

error Error: Cannot find module '@babel/core' ↓

cause @babel/core is not installed or is missing from node_modules.

fix

Run 'npm install @babel/core --save-dev' or add it to devDependencies.

error Error: Callback must be a function. Received undefined ↓

cause Attempting to import a non-existent named export (e.g., import { babel } from 'esbuild-plugin-babel-cjs').

fix

Use default import: import babel from 'esbuild-plugin-babel-cjs' or require('esbuild-plugin-babel-cjs').

error Error: No Babel configuration found ↓

cause No babel.config.json, .babelrc, or inline config provided.

fix

Create a babel.config.json in the project root or pass config option to babel().

error ReferenceError: require is not defined ↓

cause Using require() in an ESM context (e.g., 'type':'module' in package.json).

fix

Use import syntax: import babel from 'esbuild-plugin-babel-cjs';

Warnings

gotcha Plugin does not apply any transforms by default: you must provide a Babel config via babel.config.json or the 'config' option. Without one, Babel runs as a no-op. ↓

fix Create a babel.config.json or pass config object to babel({ config: { presets: [...], plugins: [...] } }).

gotcha If targeting es5, esbuild must also have target: ['es5'] set; otherwise esbuild will output modern syntax first and Babel may not produce valid es5. ↓

fix Add target: ['es5'] to esbuild.build options.

deprecated The package README references esbuild-plugin-babel (without cjs) in the example code (line: const babel = require('esbuild-plugin-babel');). This is a copy-paste error; the correct package is esbuild-plugin-babel-cjs. ↓

fix Replace require('esbuild-plugin-babel') with require('esbuild-plugin-babel-cjs').

gotcha Plugin uses a synchronous transform under the hood; large files or complex Babel presets may cause performance issues or blocking in esbuild's async pipeline. ↓

fix Consider using esbuild's own transforms when possible for performance.

gotcha The plugin namespace option defaults to an empty string, which may conflict with other plugins. Use a specific namespace like 'babel' to isolate. ↓

fix Pass babel({ namespace: 'babel' }) to avoid conflicts.

Install

npm install esbuild-plugin-babel-cjs

yarn add esbuild-plugin-babel-cjs

pnpm add esbuild-plugin-babel-cjs

Imports

plugin (default)

wrong

const babel = require('esbuild-plugin-babel-cjs').default;

correct

const babel = require('esbuild-plugin-babel-cjs');

Package uses CommonJS default export; require directly returns the plugin function.

plugin (ESM)
wrong
```
import { babel } from 'esbuild-plugin-babel-cjs';
```
correct
```
import babel from 'esbuild-plugin-babel-cjs';
```
Default import works because the module has a default export that resolves to the plugin function.

TypeScript types

wrong

import { BabelPluginConfig } from 'esbuild-plugin-babel-cjs';

correct

import type { BabelPluginConfig } from 'esbuild-plugin-babel-cjs';

Type imports are available for config interface. Named type import is correct.

Quickstart

Minimal esbuild config that applies Babel transformations via the plugin. Ensure @babel/core is installed and Babel configuration is set separately.

const esbuild = require('esbuild');
const babel = require('esbuild-plugin-babel-cjs');

esbuild.build({
  entryPoints: ['index.js'],
  bundle: true,
  outfile: 'main.js',
  plugins: [babel()],
}).catch(() => process.exit(1));