esbuild-plugin-hybrid-export

0.3.4 verified Fri May 01 auth: no javascript

Esbuild plugin to simplify creation of hybrid (dual) packages that support both ESM and CJS module formats. At version 0.3.4, it automates the generation of wrapper ESM files that re-export CJS module.exports via named exports, addressing reliability issues with Node.js's static analysis for named exports from CJS. The plugin is in PoC status, with frequent releases from the monorepo. It requires esbuild >=0.19.0. Compared to manual dual-package setup or other tools, it offers a minimal, esbuild-native solution with TypeScript support.

Common errors

error ERR_REQUIRE_ESM ↓

cause Using require() on an ESM-only package.

fix

Use dynamic import: const { hybridExportPlugin } = await import('esbuild-plugin-hybrid-export')

error TypeError: hybridExportPlugin is not a function ↓

cause Incorrect import (e.g., forgot destructuring or used default import when expecting named).

fix

Use correct import: import { hybridExportPlugin } from 'esbuild-plugin-hybrid-export' or import hybridExportPlugin from 'esbuild-plugin-hybrid-export'.

Warnings

breaking If you use esbuild < 0.19.0, the plugin will fail to install due to peer dependency mismatch. ↓

fix Upgrade esbuild to >=0.19.0.

gotcha The plugin only generates ESM wrappers; the actual output format of esbuild must be 'cjs' for the wrapper to work. ↓

fix Ensure esbuild config has format: 'cjs'.

gotcha Named exports from CJS may still be unreliable for some edge cases; the plugin relies on Node.js static analysis which can fail for dynamic exports. ↓

fix Use explicit named exports in CJS source or test thoroughly.

deprecated The package is marked as Proof of Concept (PoC) and may have breaking changes between minor versions. ↓

fix Pin to a specific version and test upgrades.

Install

npm install esbuild-plugin-hybrid-export

yarn add esbuild-plugin-hybrid-export

pnpm add esbuild-plugin-hybrid-export

Imports

hybridExportPlugin

wrong

const hybridExportPlugin = require('esbuild-plugin-hybrid-export')

correct

import { hybridExportPlugin } from 'esbuild-plugin-hybrid-export'

Package is ESM-only; CommonJS require() will fail unless using dynamic import or transpilation.

HybridExportPluginOptions

wrong

import { HybridExportPluginOptions } from 'esbuild-plugin-hybrid-export'

correct

import type { HybridExportPluginOptions } from 'esbuild-plugin-hybrid-export'

This is a TypeScript type; only import when using TypeScript, and use `import type` to avoid runtime bundling.

default export (hybridExportPlugin)
```
import hybridExportPlugin from 'esbuild-plugin-hybrid-export'
```
The package also exposes a default export, which is the same as the named export `hybridExportPlugin`.

Quickstart

Demonstrates basic usage: configure esbuild to output CJS in 'target/cjs', while the plugin generates ESM wrappers in 'target/esm' with .mjs extension.

import { build, BuildOptions } from 'esbuild'
import { hybridExportPlugin } from 'esbuild-plugin-hybrid-export'

const plugin = hybridExportPlugin({
  to: 'target/esm',
  toExt: '.mjs'
})
const config: BuildOptions = {
  entryPoints: ['index.ts'],
  outdir: 'target/cjs',
  plugins: [plugin],
  format: 'cjs'
}

await build(config)