esbuild-plugin-globals

0.2.0 verified Mon Apr 27 auth: no javascript

An esbuild plugin that replicates Webpack's externals functionality, allowing you to exclude certain modules from the bundle and replace them with global variables. Current stable version 0.2.0. It supports string patterns and RegExp with resolver functions for complex cases. Differs from native esbuild's 'external' by providing per-module global variable mapping, similar to Webpack's externals. Ships TypeScript declarations.

Common errors

error Error: The plugin "esbuild-plugin-globals" must be constructed with a non-empty object ↓

cause Calling GlobalsPlugin() without arguments or with an empty object.

fix

Pass an object with at least one module mapping.

error Error: Module "react" has been externalized but not found in globals ↓

cause The plugin is not mapping a module that is set as external elsewhere.

fix

Either add the module to the globals object or ensure it's not external.

error TypeError: globals[moduleName] is not a function ↓

cause Using a RegExp pattern with a value that is not a string or function.

fix

Ensure the value for a regex key is a function that accepts the module name and returns a string (or undefined).

Warnings

gotcha Patterns are matched against module specifiers, not file paths. Ensure your import statements use the exact module name. ↓

fix Verify that the keys in the globals object match the import specifier exactly, e.g., 'react', not './react'.

breaking In version 0.2.0, TypeScript type definitions were added. Using previous versions without @types/esbuild-plugin-globals may require manual type definitions. ↓

fix Upgrade to 0.2.0 or later.

deprecated The plugin does not support asynchronous resolver functions. Use only synchronous string or function returns. ↓

fix Ensure resolver functions return a string synchronously; async functions will not work.

Install

npm install esbuild-plugin-globals

yarn add esbuild-plugin-globals

pnpm add esbuild-plugin-globals

Imports

default

wrong

const GlobalsPlugin = require('esbuild-plugin-globals')

correct

import GlobalsPlugin from 'esbuild-plugin-globals'

ESM-only; requires module resolution or bundling.

default

wrong

const GlobalsPlugin = require('esbuild-plugin-globals')

correct

const GlobalsPlugin = require('esbuild-plugin-globals').default

For CommonJS usage, you must access .default property.

GlobalsPlugin

wrong

import { GlobalsPlugin } from 'esbuild-plugin-globals'

correct

import GlobalsPlugin from 'esbuild-plugin-globals'

Named export not available; use default import.

Quickstart

Demonstrates basic usage: mapping 'react', 'react-dom', and 'lodash' to global variables in an esbuild bundle.

import esbuild from 'esbuild';
import GlobalsPlugin from 'esbuild-plugin-globals';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  plugins: [
    GlobalsPlugin({
      'react': 'React',
      'react-dom': 'ReactDOM',
      'lodash': '_'
    })
  ],
  outfile: 'bundle.js'
});
console.log('Built with globals');