Registry / devops / esbuild-node-externals

esbuild-node-externals

library1.22.0jsnpmunverified

An esbuild plugin that automatically externalizes all Node.js built-in modules and dependencies from node_modules, so they are not bundled. Version 1.22.0 supports esbuild 0.12–0.28. It differentiates from manual externals handling by scanning package.json dependencies, devDependencies, peerDependencies, and optionalDependencies, and also externalizes Node built-ins like 'fs', 'path', etc. The plugin handles ESM and CJS outputs correctly, and works well with monorepos. It is often used alongside other esbuild plugins for Node.js bundling where the goal is to keep dependencies out of the bundle for faster builds and smaller output. The package has type definitions built-in and is released on a as-needed cadence.

devops

npm install esbuild-node-externals

package ↗

INSTALL

IMPORT

SIG · ESBUILD-NODE-EXTER

esbuild-node-externals

devopsjavascriptv1.22.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.

default

✓ import nodeExternals from 'esbuild-node-externals'

✗ const nodeExternals = require('esbuild-node-externals')

Default import works in ESM/CJS environments. CommonJS require is not recommended because the package is ESM-first since v1.

nodeExternals

✓ import { nodeExternals } from 'esbuild-node-externals'

Named export is also available for clarity.

NodeExternalsOptions

✓ import type { NodeExternalsOptions } from 'esbuild-node-externals'

Type import for TypeScript users configuring the plugin.

Basic esbuild configuration using esbuild-node-externals to exclude Node built-ins and dependencies from the bundle.

import { build } from 'esbuild'; import nodeExternals from 'esbuild-node-externals'; await build({ entryPoints: ['src/index.ts'], bundle: true, outfile: 'dist/index.js', platform: 'node', plugins: [nodeExternals()] });

Debug

Known issues

gotchaThe plugin externalizes dependencies listed in package.json. If you have transitive dependencies that are not listed, they will be bundled unless you explicitly include them.

fix

Ensure all dependencies you want external are listed in your package.json. Alternatively, use the `allowList` option to include specific packages that should still be bundled.

affects: >=1.0

deprecatedThe `modulesDir` option was deprecated in v1.16; use `packagePath` instead.

fix

Replace `modulesDir` with `packagePath` in your plugin options.

affects: >=1.16

breakingIn version 1.0, the default export was named `default`. Prior to 1.0, import was `const { default: nodeExternals } = require('esbuild-node-externals')`. CJS require breaks in v1+.

fix

Update imports to `import nodeExternals from 'esbuild-node-externals'` and ensure your project uses ESM or a bundler that handles ESM.

affects: >=1.0

gotchaThe plugin automatically externalizes Node built-in modules irrespective of the `platform` setting. If you are targeting a browser environment, you should not use this plugin as it will externalize built-ins that may not exist in the browser.

fix

Only use `esbuild-node-externals` when `platform: 'node'` or you intend to keep built-ins external.

affects: >=0.1

Errors

Common errors & fixes

Error: Cannot find module 'esbuild-node-externals'

Package not installed or incorrect import path.

fix

Run `npm install esbuild-node-externals --save-dev` and ensure import is correct: `import nodeExternals from 'esbuild-node-externals'`.

External module 'express' cannot be bundled because it's not listed in dependencies

The plugin externalizes 'express' because it's in dependencies, but the bundler expects it to be available at runtime. This is intended, but if you want to bundle it, use allowList.

fix

Add `allowList: ['express']` to the plugin options or remove 'express' from dependencies.

TypeError: nodeExternals is not a function

Using a wrong import pattern (e.g., destructuring wrong property or using CJS require incorrectly).

fix

Use `import nodeExternals from 'esbuild-node-externals'` (default import) or `import { nodeExternals } from 'esbuild-node-externals'` (named).

Upgrade

Version history

1.22.0latest on npm

Audit

Dependencies

esbuildrequiredpeer dependency; the plugin is designed to work as an esbuild plugin

Agent activity

2 hits · last 30 days

node

Resources

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