esbuild-node-externals

1.22.0 verified Fri May 01 auth: no javascript

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.

Common errors

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

cause 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'.

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

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

error TypeError: nodeExternals is not a function ↓

cause 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).

Warnings

gotcha The 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.

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

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

breaking In 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.

gotcha The 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.

Install

npm install esbuild-node-externals

yarn add esbuild-node-externals

pnpm add esbuild-node-externals

Imports

default
wrong
```
const nodeExternals = require('esbuild-node-externals')
```
correct
```
import nodeExternals from '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.

Quickstart

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()]
});