Registry / devops / esbuild-plugin-hybrid-export

esbuild-plugin-hybrid-export

library0.3.4jsnpmunverified

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.

devops

npm install esbuild-plugin-hybrid-export

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-PLUGIN-HYB

esbuild-plugin-hybrid-export

devopsjavascriptv0.3.4

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.

hybridExportPlugin

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

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

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

HybridExportPluginOptions

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

✗ import { 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`.

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)

Debug

Known issues

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

fix

Upgrade esbuild to >=0.19.0.

affects: <0.19.0

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

affects: >=0.0.1

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

affects: >=0.0.1

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

affects: <0.4.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM

Using require() on an ESM-only package.

fix

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

TypeError: hybridExportPlugin is not a function

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'`.

Upgrade

Version history

0.3.4latest on npm

Audit

Dependencies

esbuildrequiredpeer dependency; the plugin integrates with esbuild's build pipeline

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/antongolub/misc ↗

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