esbuild-plugin-external-global

1.0.1 verified Fri May 01 auth: no javascript

An esbuild plugin that maps external modules to global variables, enabling bundle-size reduction by excluding dependencies like React, ReactDOM, or jQuery and referencing them via globals such as window.React. Version 1.0.1 is stable with minimal API surface. It provides a simple mapping object where keys are module names and values are global variable expressions. The plugin is commonly used in library builds where certain dependencies are provided by the host environment. It has TypeScript types and works with both CJS and ESM esbuild configurations. Compared to similar plugins like esbuild-plugin-externalize, this one focuses specifically on global variable fallbacks rather than file-based externals.

Common errors

error Error: Build failed with 1 error: error: No matching export in "node_modules/esbuild-plugin-external-global/lib/index.js" for import "default" ↓

cause Using default import instead of named import.

fix

Change 'import externalGlobalPlugin from...' to 'import { externalGlobalPlugin } from...'.

error TypeError: Cannot read properties of undefined (reading 'onResolve') ↓

cause Plugin not added to esbuild plugins array correctly.

fix

Ensure plugin is an object with setup function: wrap result of externalGlobalPlugin() in brackets: plugins: [externalGlobalPlugin({...})].

Warnings

breaking In v1.0.0, the function name changed from 'externalGlobal' to 'externalGlobalPlugin'. ↓

fix Replace 'externalGlobal' with 'externalGlobalPlugin' in imports and usage.

gotcha The plugin does not automatically set 'external' option; you must mark those packages as external in esbuild config. ↓

fix Add 'external: ["react", "react-dom"]' to esbuild options.

gotcha Global variable expressions must evaluate to a function/object, not a string literal; incorrect quotes cause runtime errors. ↓

fix Use 'window.React' not '"window.React"'.

Install

npm install esbuild-plugin-external-global

yarn add esbuild-plugin-external-global

pnpm add esbuild-plugin-external-global

Imports

externalGlobalPlugin

wrong

const externalGlobalPlugin = require('esbuild-plugin-external-global')

correct

import { externalGlobalPlugin } from 'esbuild-plugin-external-global'

Package exports a named export, not default. CJS require destructuring works but ESM import is recommended.

esbuild
wrong
```
const esbuild = require('esbuild')
```
correct
```
import * as esbuild from 'esbuild'
```
esbuild is a peer dependency. Both CJS and ESM supported; use dynamic import for newer esbuild versions.
externalGlobalPlugin (type)
```
import type { ExternalGlobalPlugin } from 'esbuild-plugin-external-global'
```
TypeScript users can import the type for type-checking the plugin options.

Quickstart

Build a bundle excluding React and ReactDOM, expecting them as globals.

import * as esbuild from 'esbuild';
import { externalGlobalPlugin } from 'esbuild-plugin-external-global';

await esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [
    externalGlobalPlugin({
      'react': 'window.React',
      'react-dom': 'window.ReactDOM'
    })
  ]
});