esbuild-plugin-extract-helpers

0.0.10 verified Fri May 01 auth: no javascript

Esbuild plugin (v0.0.11) that extracts CommonJS helper functions (like those from tslib) into a separate shared file, reducing bundle size when multiple CJS modules are emitted. The plugin hooks into esbuild's build process to deduplicate helper injections that esbuild otherwise inlines into each CJS module. Requires esbuild >=0.19.0 as a peer dependency. Currently a PoC with a focused API surface: configure CJS glob pattern, output directory, and helper filename. Ships TypeScript declarations, targets ESM-only consumption.

Common errors

error Error: Cannot find module 'esbuild-plugin-extract-helpers' ↓

cause Package is not installed, or installed in a location not in require.resolve() path.

fix

Run npm install esbuild-plugin-extract-helpers in your project.

error TypeError: extractHelpersPlugin is not a function ↓

cause Attempted to use a default import when the package only exports named exports.

fix

Use named import: import { extractHelpersPlugin } from 'esbuild-plugin-extract-helpers'

error Error: The plugin 'extract-helpers' must be used with format 'cjs' ↓

cause The plugin is designed for CommonJS output; using it with 'esm' or 'iife' format will trigger an error.

fix

Set format: 'cjs' in the esbuild build options.

Warnings

breaking The package is ESM-only. Node.js versions that do not support ESM (Node <12) cannot load it. ↓

fix Use Node >=12 or upgrade to a version that supports ESM. Alternatively, use dynamic import() from a CommonJS file: import('esbuild-plugin-extract-helpers').then(m => m.extractHelpersPlugin(...))

gotcha The plugin only operates on files that match the `include` regex (default: /./). If your CJS files have a different extension (e.g., .js), they will be ignored. ↓

fix Adjust the `include` option to match your file patterns. For example, set include: /\.js$/

gotcha The plugin must be added to the esbuild `plugins` array **before** other plugins that may modify output files, otherwise helpers may not be correctly extracted. ↓

fix Place the extractHelpersPlugin as the first plugin in the plugins array.

deprecated Version 0.0.8 introduced a fix that removed a redundant variable. If you are on an older version, update to 0.0.11 to get the latest fixes. ↓

fix Run `npm install esbuild-plugin-extract-helpers@latest`

Install

npm install esbuild-plugin-extract-helpers

yarn add esbuild-plugin-extract-helpers

pnpm add esbuild-plugin-extract-helpers

Imports

extractHelpersPlugin

wrong

const extractHelpersPlugin = require('esbuild-plugin-extract-helpers')

correct

import { extractHelpersPlugin } from 'esbuild-plugin-extract-helpers'

The package is ESM-only; CommonJS require() will fail. Use dynamic import() if necessary.

PluginOptions
wrong
```
const { PluginOptions } = require('esbuild-plugin-extract-helpers')
```
correct
```
import type { PluginOptions } from 'esbuild-plugin-extract-helpers'
```
PluginOptions is a TypeScript type; it is not exported at runtime. The wrong pattern would cause a runtime error if used as a value.
default export
wrong
```
import extractHelpersPlugin, { PluginOptions } from 'esbuild-plugin-extract-helpers'
```
correct
```
import extractHelpersPlugin from 'esbuild-plugin-extract-helpers'
```
The package does not have a default export; only named exports are available. Attempting a default import yields undefined at runtime.

Quickstart

Demonstrates basic usage: creates the plugin with custom CJS output directory, file inclusion pattern, and helper filename, then invokes esbuild build with CJS format.

import { build } from 'esbuild'
import { extractHelpersPlugin } from 'esbuild-plugin-extract-helpers'

const plugin = extractHelpersPlugin({
  cwd: 'dist',
  include: /\.cjs$/,
  helper: 'helpers.cjs'
})

await build({
  entryPoints: ['src/index.ts'],
  outdir: 'dist',
  format: 'cjs',
  plugins: [plugin],
  bundle: true
})