rollup-plugin-external-globals

0.13.0 verified Mon Apr 27 auth: no javascript

A Rollup plugin that transforms external import statements (static and dynamic) into global variable references, similar to Rollup's built-in output.globals option but with broader support. Version 0.13.0 requires Rollup ^2.25.0 || ^3.3.0 || ^4.1.4. It uses a moduleId-to-variableName map (object or function) to rewrite imports to direct globals, helping in scenarios like bundling for browser environments where dependencies are loaded via script tags. Key differentiators: it works with dynamic imports, supports include/exclude patterns via picomatch, provides a custom dynamic wrapper, and can use const bindings via the constBindings option. It ships TypeScript types.

Common errors

error Error: [plugin external-globals] Could not resolve import 'jquery' ↓

cause The plugin marks the module as external but Rollup cannot resolve it because the module is not installed or not listed in external.

fix

Add the module to output.globals or ensure it's listed in external options.

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

cause Dynamic import transformation returns a global variable that is not an object with a default property, and the code expects a module namespace with default.

fix

Set dynamicWrapper to a function that returns the global variable directly, e.g., () => 'Promise.resolve({ default: myGlobal })'.

error Error: Unknown plugin hook: 'debug' ↓

cause Using version >=0.12.1 but Rollup version is 2.x where debug hook is not available.

fix

Upgrade Rollup to 3.x or 4.x, or downgrade plugin to 0.12.0.

Warnings

breaking v0.12.0 changed variable declaration from `var` to `const`? Actually default is `var`, with `constBindings` option. Also throws on export all declaration. ↓

fix If you rely on variable hoisting, the default `var` might be fine; if you need `const`, set `constBindings: true`. Avoid `export * from` with external globals.

breaking v0.9.0 bumped minimal Rollup version to 4.x. ↓

fix Update Rollup to version 4 or later.

gotcha Plugin does not transform require() calls; only import/export statements. ↓

fix Place this plugin after rollup-plugin-commonjs or other CJS transformers.

gotcha Dynamic import transformed to `Promise.resolve(global)` – the resolved object is always a module namespace, but global variable might not be. ↓

fix Ensure the global variable returns the expected default or shape; consider setting `dynamicWrapper` to adjust.

deprecated v0.13.0 changed include/exclude signature (now uses picomatch). ↓

fix Update include/exclude patterns to picomatch syntax if you were using older patterns.

Install

npm install rollup-plugin-external-globals

yarn add rollup-plugin-external-globals

pnpm add rollup-plugin-external-globals

Imports

default

wrong

const externalGlobals = require('rollup-plugin-external-globals')

correct

import externalGlobals from 'rollup-plugin-external-globals'

Esm-only; CommonJS require is not supported

createPlugin
```
import { createPlugin } from 'rollup-plugin-external-globals'
```
Named export 'createPlugin' is available, but default export is the same function (these are equivalent)
Plugin
```
import type { Plugin } from 'rollup-plugin-external-globals'
```
The package exports TypeScript types; import type for type declarations

Quickstart

Shows basic usage: map jquery import to global $ variable in a Rollup configuration.

import externalGlobals from 'rollup-plugin-external-globals';

export default {
  input: 'src/index.js',
  output: {
    dir: 'dist',
    format: 'es'
  },
  plugins: [
    externalGlobals({
      jquery: '$'
    })
  ]
};