esbuild-shim-plugin

1.0.3 verified Mon Apr 27 auth: no javascript

An esbuild plugin that polyfills import.meta.url for ESM modules and require/__filename/__dirname for CommonJS modules. Stable v1.0.3, released 2023. Lightweight, zero dependencies, ships TypeScript types. Key differentiator: solves the common problem of using Node.js module globals when bundling with esbuild, especially useful for mixed CJS/ESM codebases. Release cadence is low; no major changes expected.

Common errors

error Cannot find module 'esbuild-shim-plugin' ↓

cause Module not installed or not in node_modules.

fix

Run npm install esbuild-shim-plugin --save-dev or pnpm add -D esbuild-shim-plugin.

error require() of ES Module esbuild-shim-plugin from CJS not supported ↓

cause Trying to use require() to load the ESM-only package.

fix

Use import { shimPlugin } from 'esbuild-shim-plugin' and ensure your project uses ESM or dynamic import.

error The requested module 'esbuild-shim-plugin' does not provide an export named 'default' ↓

cause Default import used when the package only provides named exports.

fix

Use import { shimPlugin } from 'esbuild-shim-plugin' instead of import shimPlugin from 'esbuild-shim-plugin'.

Warnings

gotcha shimPlugin() adds polyfill code that may increase bundle size and affect runtime performance. ↓

fix Only use the plugin when you actually need to access require, __filename, __dirname, or import.meta.url in bundled code. Consider alternatives like setting the 'platform' to 'node'.

breaking The package is ESM-only and cannot be required() in CommonJS contexts. ↓

fix Use dynamic import() or ensure your project is configured for ESM.

deprecated No public API changes are expected, but no stability guarantees are documented. ↓

fix Pin to a specific version if you rely on exact behavior.

gotcha The plugin may conflict with other esbuild plugins that modify import/require behavior. ↓

fix Test plugin order and compatibility when using multiple esbuild plugins.

Install

npm install esbuild-shim-plugin

yarn add esbuild-shim-plugin

pnpm add esbuild-shim-plugin

Imports

shimPlugin
wrong
```
const shimPlugin = require('esbuild-shim-plugin')
```
correct
```
import { shimPlugin } from 'esbuild-shim-plugin'
```
Default export is not available; use named import. CommonJS require fails because esbuild-shim-plugin is ESM-only.
shimPlugin
wrong
```
import shimPlugin from 'esbuild-shim-plugin'
```
correct
```
import { shimPlugin } from 'esbuild-shim-plugin'
```
The package exports a named export, not a default export. Attempting default import will result in undefined.
shimPlugin
wrong
```
const { shimPlugin } = require('esbuild-shim-plugin')
```
correct
```
import { shimPlugin } from 'esbuild-shim-plugin'
```
The package is ESM-only since v1.0.0, so require() is not supported in CommonJS contexts.

Quickstart

Bundles an ESM project using esbuild with shimPlugin to polyfill import.meta.url, require, __filename, and __dirname.

import { build } from 'esbuild';
import { shimPlugin } from 'esbuild-shim-plugin';

await build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  format: 'esm',
  outfile: 'dist/index.js',
  plugins: [shimPlugin()],
});