{"id":25304,"library":"esbuild-node-externals","title":"esbuild-node-externals","description":"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.","status":"active","version":"1.22.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","esbuild","node_modules","esbuild-plugin","bundle","typescript"],"install":[{"cmd":"npm install esbuild-node-externals","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-node-externals","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-node-externals","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency; the plugin is designed to work as an esbuild plugin","package":"esbuild","optional":false}],"imports":[{"note":"Default import works in ESM/CJS environments. CommonJS require is not recommended because the package is ESM-first since v1.","wrong":"const nodeExternals = require('esbuild-node-externals')","symbol":"default","correct":"import nodeExternals from 'esbuild-node-externals'"},{"note":"Named export is also available for clarity.","wrong":"","symbol":"nodeExternals","correct":"import { nodeExternals } from 'esbuild-node-externals'"},{"note":"Type import for TypeScript users configuring the plugin.","wrong":"","symbol":"NodeExternalsOptions","correct":"import type { NodeExternalsOptions } from 'esbuild-node-externals'"}],"quickstart":{"code":"import { build } from 'esbuild';\nimport nodeExternals from 'esbuild-node-externals';\n\nawait build({\n  entryPoints: ['src/index.ts'],\n  bundle: true,\n  outfile: 'dist/index.js',\n  platform: 'node',\n  plugins: [nodeExternals()]\n});","lang":"typescript","description":"Basic esbuild configuration using esbuild-node-externals to exclude Node built-ins and dependencies from the bundle."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Replace `modulesDir` with `packagePath` in your plugin options.","message":"The `modulesDir` option was deprecated in v1.16; use `packagePath` instead.","severity":"deprecated","affected_versions":">=1.16"},{"fix":"Update imports to `import nodeExternals from 'esbuild-node-externals'` and ensure your project uses ESM or a bundler that handles ESM.","message":"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+.","severity":"breaking","affected_versions":">=1.0"},{"fix":"Only use `esbuild-node-externals` when `platform: 'node'` or you intend to keep built-ins external.","message":"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.","severity":"gotcha","affected_versions":">=0.1"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run `npm install esbuild-node-externals --save-dev` and ensure import is correct: `import nodeExternals from 'esbuild-node-externals'`.","cause":"Package not installed or incorrect import path.","error":"Error: Cannot find module 'esbuild-node-externals'"},{"fix":"Add `allowList: ['express']` to the plugin options or remove 'express' from 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.","error":"External module 'express' cannot be bundled because it's not listed in dependencies"},{"fix":"Use `import nodeExternals from 'esbuild-node-externals'` (default import) or `import { nodeExternals } from 'esbuild-node-externals'` (named).","cause":"Using a wrong import pattern (e.g., destructuring wrong property or using CJS require incorrectly).","error":"TypeError: nodeExternals is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}