Registry / devops / esbuild-externals-plugin

esbuild-externals-plugin

library1.4.0jsnpmunverified

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.

devops

npm install esbuild-externals-plugin

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ESBUILD-EXTERNALS-

esbuild-externals-plugin

devopsjavascriptv1.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

externalsPlugin

✓ import { externalsPlugin } from 'esbuild-externals-plugin'

✗ const externalsPlugin = require('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)

✓ import { externalsPlugin } from 'esbuild-externals-plugin'

✗ 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)

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

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

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

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));

Debug

Known issues

breakingIn 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.

affects: >=1.3.0

gotchaThe 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.

affects: >=1.0.0

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

fix

Update esbuild to version >=0.18.

affects: >=1.0.0

gotchaWhen 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').

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: externalsPlugin is not a function

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: The plugin 'esbuild-externals-plugin' must be called with an array of strings.

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']).

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

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.

Upgrade

Version history

1.4.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/smapiot/piral-cli-esbuild ↗

packagehttps://www.npmjs.com/package/esbuild-externals-plugin ↗

homepagehttps://piral.io ↗