{"id":21268,"library":"esbuild-plugin-node-externals","title":"esbuild-plugin-node-externals","description":"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.","status":"active","version":"1.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/LinbuduLab/esbuild-plugins","tags":["javascript","ESBuild","plugin","typescript"],"install":[{"cmd":"npm install esbuild-plugin-node-externals","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-node-externals","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-node-externals","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required to use the plugin — must be >= 0.14.0.","package":"esbuild","optional":false}],"imports":[{"note":"Named export only; default import does not exist.","wrong":"import nodeExternals from 'esbuild-plugin-node-externals'","symbol":"nodeExternals","correct":"import { nodeExternals } from 'esbuild-plugin-node-externals'"},{"note":"For TypeScript users: this is a type export; import with `type` to avoid bundling.","wrong":"import { NodeExternalsOptions } from 'esbuild-plugin-node-externals'","symbol":"NodeExternalsOptions","correct":"import type { NodeExternalsOptions } from 'esbuild-plugin-node-externals'"},{"note":"CommonJS must destructure; default require is wrong.","wrong":"const nodeExternals = require('esbuild-plugin-node-externals')","symbol":"nodeExternals (CommonJS)","correct":"const { nodeExternals } = require('esbuild-plugin-node-externals')"}],"quickstart":{"code":"import { build } from 'esbuild';\nimport { nodeExternals } from 'esbuild-plugin-node-externals';\n\nasync function bundle() {\n  const result = await build({\n    entryPoints: ['src/index.ts'],\n    bundle: true,\n    outfile: 'dist/bundle.js',\n    plugins: [\n      nodeExternals({\n        packagePaths: 'package.json',\n        withDeps: true,\n        withDevDeps: false,\n        include: ['lodash'],\n      }),\n    ],\n  });\n  console.log('Build succeeded:', result);\n}\n\nbundle().catch(err => console.error(err));","lang":"typescript","description":"This example shows a minimal ESBuild bundle config using nodeExternals to externalize production deps, skip devDeps, and include 'lodash' in the bundle."},"warnings":[{"fix":"Use `import { nodeExternals } from 'esbuild-plugin-node-externals'` instead of `import nodeExternals from 'esbuild-plugin-node-externals'`.","message":"Version 1.0.0 changed the export from default to named export.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always specify `packagePaths: 'package.json'` or an array of paths to avoid unexpected behavior.","message":"The `packagePaths` option previously defaulted to process.cwd() but now must be explicitly provided in some versions.","severity":"deprecated","affected_versions":">=0.5.0"},{"fix":"Use `include` to force-bundle specific packages; no code change needed, just understanding the precedence.","message":"If `include` contains a package that is also externalized via `withDeps`, it will still be bundled. Priority: include > externalize.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Manually add missing dependencies to package.json or to the `include` option to control bundling.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run `npm install esbuild-plugin-node-externals --save-dev` and ensure peer dependency esbuild >= 0.14.0 is installed.","cause":"Plugin not installed or version mismatch.","error":"Error: Cannot find module 'esbuild-plugin-node-externals'"},{"fix":"Use `import { nodeExternals } from 'esbuild-plugin-node-externals'` instead.","cause":"Importing as default import but the package only exports `nodeExternals` as a named export.","error":"TypeScript error: Module 'esbuild-plugin-node-externals' has no default export."},{"fix":"Provide `packagePaths: 'package.json'` in the plugin options, or an array of paths.","cause":"The `packagePaths` option was omitted or set to undefined in a version that requires it.","error":"Error: [plugin: node-externals] packagePaths option is required"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}