esbuild-plugin-ignore-module

0.5.1 verified Fri May 01 auth: no javascript

ESBuild plugin to ignore specific module imports during bundling. Current stable version is 0.5.1, maintained and updated occasionally. It allows you to specify module names or patterns to be replaced with empty objects, useful for stripping out server-only or optional dependencies in browser builds. Key differentiator: simple, type-safe (ships TypeScript definitions), and integrates seamlessly with ESBuild's plugin system. Alternatives like `esbuild-plugin-external` fully externalize modules, while this plugin mocks them.

Common errors

error Error: Cannot find module 'esbuild-plugin-ignore-module' ↓

cause Package not installed or peer dependency `esbuild` version mismatch.

fix

Run npm install esbuild-plugin-ignore-module esbuild (esbuild as peer dep).

error TypeError: ignoreModule is not a function ↓

cause Using the old API name `ignoreModule` from versions <0.5.0.

fix

Use ignoreModulePlugin instead: import { ignoreModulePlugin } from 'esbuild-plugin-ignore-module'.

error error: No matching export in "esbuild-plugin-ignore-module" for import "default" ↓

cause Trying to default-import in a CommonJS context.

fix

Use named import: import { ignoreModulePlugin } from 'esbuild-plugin-ignore-module' or use dynamic import.

Warnings

gotcha The plugin replaces ignored modules with an empty object `{}`. This may cause runtime errors if code expects those modules to exist. ↓

fix Ensure your code handles the absence of these modules, e.g., with optional chaining or conditional checks.

breaking Version 0.5.0 changed the plugin's API from `ignoreModule` to `ignoreModulePlugin`. Old code using `import { ignoreModule } from 'esbuild-plugin-ignore-module'` will break. ↓

fix Update imports to use `ignoreModulePlugin` instead of `ignoreModule`.

deprecated Specifying strings directly in the `modules` array is deprecated; use objects with `{ name: 'moduleName' }` instead. ↓

fix Convert each string to an object: `{ name: 'moduleName' }`.

Install

npm install esbuild-plugin-ignore-module

yarn add esbuild-plugin-ignore-module

pnpm add esbuild-plugin-ignore-module

Imports

ignoreModulePlugin

wrong

const ignoreModulePlugin = require('esbuild-plugin-ignore-module')

correct

import { ignoreModulePlugin } from 'esbuild-plugin-ignore-module'

ESM-only; no CJS export. Use dynamic import if needed.

IgnoreModuleOption

wrong

import { IgnoreModuleOption } from 'esbuild-plugin-ignore-module'

correct

import type { IgnoreModuleOption } from 'esbuild-plugin-ignore-module'

This is a type export, only available when using TypeScript or with `import type`.

default

wrong

import { default } from 'esbuild-plugin-ignore-module'

correct

import ignoreModulePlugin from 'esbuild-plugin-ignore-module'

Default export is the plugin function itself; named export exists too.

Quickstart

This example shows how to ignore Node.js built-in modules (fs, path, crypto) during bundling, replacing them with empty objects.

import { build } from 'esbuild';
import { ignoreModulePlugin } from 'esbuild-plugin-ignore-module';

await build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/out.js',
  plugins: [
    ignoreModulePlugin({
      modules: ['fs', 'path', 'crypto']
    })
  ]
});