@fal-works/esbuild-plugin-global-externals

esbuild-plugin-global-externals

esbuild plugin for replacing imports with global variables.

Similar to (but not the same as) output.globals option of Rollup. See also: evanw/esbuild#337

Originally developed with esbuild v0.8.40, and should work with higher versions as well.

TL;DR

This:

import p5 from "p5";
new p5();

transpiles to:

// Here a variable `p5` should be defined globally (typically via UMD)
var p5_default = p5;
new p5_default();

Usage example

import { globalExternals } from "@fal-works/esbuild-plugin-global-externals";

/** Mapping from module paths to global variables */
const globals = {
  jquery: "$"
};

esbuild.build({
  entryPoints: ["src/main.js"],
  outfile: "dist/bundle.js",
  bundle: true,
  plugins: [globalExternals(globals)],
});

If you prefer RegExp use globalExternalsWithRegExp() instead, however note that the RegExp you'll pass should be valid in Go language as well.

Configuration

Instead of simply providing variable names only, you can pass ModuleInfo objects to configure the loading behavior for each module.

Module type

Either "esm" (default) or "cjs".

This determines the internal behavior of this plugin when loading modules (which affects the code after bundling as well).

globalExternals({
  "someModulePath": {
    varName: "someGlobalVar",
    type: "cjs"
  }
})

Named/default export

If type: "esm" and also if you're doing named import with some modules in question, you have to tell which variables from each module should be importable.

Additionally, if you don't do default import/export, you can prevent emitting code for this with defaultExport: false.

Both have no effects if type: "cjs" (which should work fine with named imports as well).

globalExternals({
  "someModulePath": {
    varName: "someGlobalVar",
    namedExports: ["someExportedVar"],
    defaultExport: false
  }
})

The example above enables the following even if type: "esm":

import { someExportedVar } from "someModulePath";

which transpiles to:

var someExportedVar = someGlobalVar.someExportedVar;