esbuild-plugin-node-externals

1.0.1 verified Mon Apr 27 auth: no javascript

An ESBuild plugin to automatically mark Node.js dependencies (runtime, dev, peer, optional) as external during bundling. Current stable version is 1.0.1, actively maintained on GitHub with TypeScript types included. Key differentiator: provides granular control over which dependency categories to externalize (deps, devDeps, peerDeps, optDeps) and allows selective inclusion of specific packages. Alternatives like `esbuild-node-externals` offer less configuration flexibility.

Common errors

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

cause Plugin not installed or version mismatch.

fix

Run npm install esbuild-plugin-node-externals --save-dev and ensure peer dependency esbuild >= 0.14.0 is installed.

error TypeScript error: Module 'esbuild-plugin-node-externals' has no default export. ↓

cause Importing as default import but the package only exports `nodeExternals` as a named export.

fix

Use import { nodeExternals } from 'esbuild-plugin-node-externals' instead.

error Error: [plugin: node-externals] packagePaths option is required ↓

cause The `packagePaths` option was omitted or set to undefined in a version that requires it.

fix

Provide packagePaths: 'package.json' in the plugin options, or an array of paths.

Warnings

breaking Version 1.0.0 changed the export from default to named export. ↓

fix Use `import { nodeExternals } from 'esbuild-plugin-node-externals'` instead of `import nodeExternals from 'esbuild-plugin-node-externals'`.

deprecated The `packagePaths` option previously defaulted to process.cwd() but now must be explicitly provided in some versions. ↓

fix Always specify `packagePaths: 'package.json'` or an array of paths to avoid unexpected behavior.

gotcha If `include` contains a package that is also externalized via `withDeps`, it will still be bundled. Priority: include > externalize. ↓

fix Use `include` to force-bundle specific packages; no code change needed, just understanding the precedence.

gotcha The plugin only marks packages listed in package.json as external. If a package is not in any dependency list, it will be bundled by default. ↓

fix Manually add missing dependencies to package.json or to the `include` option to control bundling.

Install

npm install esbuild-plugin-node-externals

yarn add esbuild-plugin-node-externals

pnpm add esbuild-plugin-node-externals

Imports

nodeExternals

wrong

import nodeExternals from 'esbuild-plugin-node-externals'

correct

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

Named export only; default import does not exist.

NodeExternalsOptions

wrong

import { NodeExternalsOptions } from 'esbuild-plugin-node-externals'

correct

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

For TypeScript users: this is a type export; import with `type` to avoid bundling.

nodeExternals (CommonJS)

wrong

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

correct

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

CommonJS must destructure; default require is wrong.

Quickstart

This example shows a minimal ESBuild bundle config using nodeExternals to externalize production deps, skip devDeps, and include 'lodash' in the bundle.

import { build } from 'esbuild';
import { nodeExternals } from 'esbuild-plugin-node-externals';

async function bundle() {
  const result = await build({
    entryPoints: ['src/index.ts'],
    bundle: true,
    outfile: 'dist/bundle.js',
    plugins: [
      nodeExternals({
        packagePaths: 'package.json',
        withDeps: true,
        withDevDeps: false,
        include: ['lodash'],
      }),
    ],
  });
  console.log('Build succeeded:', result);
}

bundle().catch(err => console.error(err));