{"id":25280,"library":"esbuild-externals-plugin","title":"esbuild-externals-plugin","description":"An esbuild plugin that provides fine-grained control over external dependencies, ensuring that when a package like 'rxjs' is marked external, its subpath imports (e.g., 'rxjs/operators') are not also externalized unless explicitly specified. This prevents surprises in microfrontend or library builds where partial bundling of submodules is desired. Current stable version is 1.4.0, released as part of the piral-cli-esbuild ecosystem. Actively maintained with a strong focus on correct external handling for monorepos and shared dependency scenarios. Ships TypeScript types. Requires Node >=16.0.","status":"active","version":"1.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/smapiot/piral-cli-esbuild","tags":["javascript","plugin","esbuild","build","microfrontend","externals","typescript"],"install":[{"cmd":"npm install esbuild-externals-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-externals-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-externals-plugin","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"CommonJS require works, but ESM import is preferred. The package exports a named function, not a default export.","wrong":"const externalsPlugin = require('esbuild-externals-plugin')","symbol":"externalsPlugin","correct":"import { externalsPlugin } from 'esbuild-externals-plugin'"},{"note":"There is no default export; only a named export. Using a default import will result in undefined.","wrong":"import externalsPlugin from 'esbuild-externals-plugin'","symbol":"externalsPlugin (default import mistake)","correct":"import { externalsPlugin } from 'esbuild-externals-plugin'"},{"note":"CommonJS usage should destructure the named export. There is no .default property.","wrong":"const externalsPlugin = require('esbuild-externals-plugin').default","symbol":"externalsPlugin (CJS)","correct":"const { externalsPlugin } = require('esbuild-externals-plugin')"}],"quickstart":{"code":"const { build } = require('esbuild');\nconst { externalsPlugin } = require('esbuild-externals-plugin');\n\nbuild({\n  entryPoints: ['src/index.js'],\n  outfile: 'dist/bundle.js',\n  bundle: true,\n  plugins: [externalsPlugin(['lodash', 'react'])],\n}).catch(() => process.exit(1));","lang":"javascript","description":"Shows how to use externalsPlugin with esbuild to externalize 'lodash' and 'react' while keeping subpath imports like 'lodash/fp' bundled."},"warnings":[{"fix":"Update Node.js to version >=20.18.1.","message":"In v1.3.0, required Node.js version was raised to >=20.18.1 for security reasons.","severity":"breaking","affected_versions":">=1.3.0"},{"fix":"Either add each subpath individually to the externals list or rely on the default esbuild externals behavior.","message":"The plugin only externalizes the exact package names provided; subpath imports (e.g., 'rxjs/operators') are NOT externalized. If you need subpaths external, you must list them explicitly.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update esbuild to version >=0.18.","message":"Support for esbuild versions before 0.18 is deprecated and may be removed in future releases.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Use destructured require: const { externalsPlugin } = require('esbuild-externals-plugin').","message":"When using CJS require, the exported function is named, not default. Using require('esbuild-externals-plugin').default yields undefined.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use import { externalsPlugin } from 'esbuild-externals-plugin' or const { externalsPlugin } = require('esbuild-externals-plugin').","cause":"Importing the module incorrectly, e.g., using default import instead of named import.","error":"TypeError: externalsPlugin is not a function"},{"fix":"Call externalsPlugin with an array: externalsPlugin(['lodash', 'react']).","cause":"Passing arguments that are not an array of strings (e.g., a single string or incorrect type).","error":"Error: The plugin 'esbuild-externals-plugin' must be called with an array of strings."},{"fix":"Add 'rxjs/operators' explicitly to the externals array if you need it external.","cause":"Expecting subpath imports to be externalized, but the plugin only externalizes the base package.","error":"Module not found: Error: Can't resolve 'rxjs/operators'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}