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

What is @fal-works/esbuild-plugin-global-externals?

The @fal-works/esbuild-plugin-global-externals npm package is designed to work with the esbuild bundler, allowing developers to exclude specific modules from the bundle and instead treat them as global variables provided at runtime. This is particularly useful for large libraries or frameworks that are included via a CDN or are already present in the global scope of the user's environment.

What are @fal-works/esbuild-plugin-global-externals's main functionalities?

Exclude specific modules

This feature allows developers to exclude modules like React and ReactDOM from the bundle. These excluded modules are then accessed as global variables, which must be included in the global scope separately, typically via a script tag in HTML.

require('esbuild').build({
  entryPoints: ['app.js'],
  bundle: true,
  outfile: 'out.js',
  plugins: [
    require('@fal-works/esbuild-plugin-global-externals')({
      react: 'React',
      'react-dom': 'ReactDOM'
    })
  ]
});

Other packages similar to @fal-works/esbuild-plugin-global-externals

esbuild-plugin-external-global

Similar to @fal-works/esbuild-plugin-global-externals, this package provides functionality to exclude specific modules from esbuild bundles and map them to global variables. The main difference lies in the configuration options and possibly the implementation details, which might affect performance or compatibility with different versions of esbuild.

README

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;