{"id":25348,"library":"esbuild-plugin-hybrid-export","title":"esbuild-plugin-hybrid-export","description":"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.","status":"active","version":"0.3.4","language":"javascript","source_language":"en","source_url":"https://github.com/antongolub/misc","tags":["javascript","esbuild","plugin","dual","hybrid","esm","cjs","typescript"],"install":[{"cmd":"npm install esbuild-plugin-hybrid-export","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-hybrid-export","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-hybrid-export","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency; the plugin integrates with esbuild's build pipeline","package":"esbuild","optional":false}],"imports":[{"note":"Package is ESM-only; CommonJS require() will fail unless using dynamic import or transpilation.","wrong":"const hybridExportPlugin = require('esbuild-plugin-hybrid-export')","symbol":"hybridExportPlugin","correct":"import { hybridExportPlugin } from 'esbuild-plugin-hybrid-export'"},{"note":"This is a TypeScript type; only import when using TypeScript, and use `import type` to avoid runtime bundling.","wrong":"import { HybridExportPluginOptions } from 'esbuild-plugin-hybrid-export'","symbol":"HybridExportPluginOptions","correct":"import type { HybridExportPluginOptions } from 'esbuild-plugin-hybrid-export'"},{"note":"The package also exposes a default export, which is the same as the named export `hybridExportPlugin`.","wrong":"","symbol":"default export (hybridExportPlugin)","correct":"import hybridExportPlugin from 'esbuild-plugin-hybrid-export'"}],"quickstart":{"code":"import { build, BuildOptions } from 'esbuild'\nimport { hybridExportPlugin } from 'esbuild-plugin-hybrid-export'\n\nconst plugin = hybridExportPlugin({\n  to: 'target/esm',\n  toExt: '.mjs'\n})\nconst config: BuildOptions = {\n  entryPoints: ['index.ts'],\n  outdir: 'target/cjs',\n  plugins: [plugin],\n  format: 'cjs'\n}\n\nawait build(config)","lang":"typescript","description":"Demonstrates basic usage: configure esbuild to output CJS in 'target/cjs', while the plugin generates ESM wrappers in 'target/esm' with .mjs extension."},"warnings":[{"fix":"Upgrade esbuild to >=0.19.0.","message":"If you use esbuild < 0.19.0, the plugin will fail to install due to peer dependency mismatch.","severity":"breaking","affected_versions":"<0.19.0"},{"fix":"Ensure esbuild config has format: 'cjs'.","message":"The plugin only generates ESM wrappers; the actual output format of esbuild must be 'cjs' for the wrapper to work.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Use explicit named exports in CJS source or test thoroughly.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Pin to a specific version and test upgrades.","message":"The package is marked as Proof of Concept (PoC) and may have breaking changes between minor versions.","severity":"deprecated","affected_versions":"<0.4.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use dynamic import: `const { hybridExportPlugin } = await import('esbuild-plugin-hybrid-export')`","cause":"Using require() on an ESM-only package.","error":"ERR_REQUIRE_ESM"},{"fix":"Use correct import: `import { hybridExportPlugin } from 'esbuild-plugin-hybrid-export'` or `import hybridExportPlugin from 'esbuild-plugin-hybrid-export'`.","cause":"Incorrect import (e.g., forgot destructuring or used default import when expecting named).","error":"TypeError: hybridExportPlugin is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}