esbuild-externals-plugin

1.4.0 verified Fri May 01 auth: no javascript

An esbuild plugin that provides fine-grained control over external dependencies, ensuring that when a package like 'rxjs' is marked external, its subpath imports (e.g., 'rxjs/operators') are not also externalized unless explicitly specified. This prevents surprises in microfrontend or library builds where partial bundling of submodules is desired. Current stable version is 1.4.0, released as part of the piral-cli-esbuild ecosystem. Actively maintained with a strong focus on correct external handling for monorepos and shared dependency scenarios. Ships TypeScript types. Requires Node >=16.0.

Common errors

error TypeError: externalsPlugin is not a function ↓

cause Importing the module incorrectly, e.g., using default import instead of named import.

fix

Use import { externalsPlugin } from 'esbuild-externals-plugin' or const { externalsPlugin } = require('esbuild-externals-plugin').

error Error: The plugin 'esbuild-externals-plugin' must be called with an array of strings. ↓

cause Passing arguments that are not an array of strings (e.g., a single string or incorrect type).

fix

Call externalsPlugin with an array: externalsPlugin(['lodash', 'react']).

error Module not found: Error: Can't resolve 'rxjs/operators' ↓

cause Expecting subpath imports to be externalized, but the plugin only externalizes the base package.

fix

Add 'rxjs/operators' explicitly to the externals array if you need it external.

Warnings

breaking In v1.3.0, required Node.js version was raised to >=20.18.1 for security reasons. ↓

fix Update Node.js to version >=20.18.1.

gotcha The plugin only externalizes the exact package names provided; subpath imports (e.g., 'rxjs/operators') are NOT externalized. If you need subpaths external, you must list them explicitly. ↓

fix Either add each subpath individually to the externals list or rely on the default esbuild externals behavior.

deprecated Support for esbuild versions before 0.18 is deprecated and may be removed in future releases. ↓

fix Update esbuild to version >=0.18.

gotcha When using CJS require, the exported function is named, not default. Using require('esbuild-externals-plugin').default yields undefined. ↓

fix Use destructured require: const { externalsPlugin } = require('esbuild-externals-plugin').

Install

npm install esbuild-externals-plugin

yarn add esbuild-externals-plugin

pnpm add esbuild-externals-plugin

Imports

externalsPlugin
wrong
```
const externalsPlugin = require('esbuild-externals-plugin')
```
correct
```
import { externalsPlugin } from 'esbuild-externals-plugin'
```
CommonJS require works, but ESM import is preferred. The package exports a named function, not a default export.
externalsPlugin (default import mistake)
wrong
```
import externalsPlugin from 'esbuild-externals-plugin'
```
correct
```
import { externalsPlugin } from 'esbuild-externals-plugin'
```
There is no default export; only a named export. Using a default import will result in undefined.

externalsPlugin (CJS)

wrong

const externalsPlugin = require('esbuild-externals-plugin').default

correct

const { externalsPlugin } = require('esbuild-externals-plugin')

CommonJS usage should destructure the named export. There is no .default property.

Quickstart

Shows how to use externalsPlugin with esbuild to externalize 'lodash' and 'react' while keeping subpath imports like 'lodash/fp' bundled.

const { build } = require('esbuild');
const { externalsPlugin } = require('esbuild-externals-plugin');

build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/bundle.js',
  bundle: true,
  plugins: [externalsPlugin(['lodash', 'react'])],
}).catch(() => process.exit(1));