{"id":22146,"library":"rollup-plugin-node-externals","title":"rollup-plugin-node-externals","description":"A Rollup/Vite plugin that automatically marks Node.js built-in modules and npm dependencies (dependencies, peerDependencies, optionalDependencies, or devDependencies) as external in your bundle configuration. Version 9.0.1 is the latest stable release, released monthly, requiring Node.js >= 24 and Rollup >= 4 or Vite >= 5. It is zero-dependency, lightweight (<10 kB), and supports monorepos and all package managers. Compared to alternatives like rollup-plugin-auto-external, it offers finer-grained control over which dependency categories to externalize and includes options for handling the node: prefix on builtins.","status":"active","version":"9.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/Septh/rollup-plugin-node-externals","tags":["javascript","rollup","vite","plugin","rollup-plugin","vite-plugin","external","externals","node","typescript"],"install":[{"cmd":"npm install rollup-plugin-node-externals","lang":"bash","label":"npm"},{"cmd":"yarn add rollup-plugin-node-externals","lang":"bash","label":"yarn"},{"cmd":"pnpm add rollup-plugin-node-externals","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM-only; CommonJS require will fail with ERR_REQUIRE_ESM.","wrong":"const nodeExternals = require('rollup-plugin-node-externals')","symbol":"default","correct":"import nodeExternals from 'rollup-plugin-node-externals'"},{"note":"Named export also available; both default and named exports reference the same factory function.","wrong":null,"symbol":"nodeExternals","correct":"import { nodeExternals } from 'rollup-plugin-node-externals'"},{"note":"TypeScript users: types are shipped with the package; import for options typing.","wrong":null,"symbol":"nodeExternals (type)","correct":"import type { NodeExternalsOptions } from 'rollup-plugin-node-externals'"}],"quickstart":{"code":"// rollup.config.js\nimport nodeExternals from 'rollup-plugin-node-externals';\n\nexport default {\n  input: 'src/index.js',\n  output: { dir: 'dist', format: 'cjs' },\n  plugins: [\n    nodeExternals({\n      builtins: true,\n      deps: true,\n      devDeps: false,\n      peerDeps: true,\n      optDeps: true,\n      builtinsPrefix: 'add',\n      exclude: ['my-local-module']\n    })\n  ]\n};","lang":"typescript","description":"Basic Rollup config using nodeExternals to externalize Node builtins and runtime dependencies, excluding a local module from externalization."},"warnings":[{"fix":"Upgrade to Rollup 4+ and Node.js 24+.","message":"Version 9.0.0 dropped support for Rollup 3 and Node.js < 24.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"If using `builtinsPrefix: false`, it now strips the prefix (equivalent to 'strip'). Use `builtinsPrefix: 'ignore'` to ignore prefix entirely.","message":"Version 9.0.0 changed the default value of `builtinsPrefix` option from 'add' to 'add' (no change) but accepts boolean `true` as 'add' and `false` as 'strip'.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Remove async/await from plugin creation; revert to synchronous factory.","message":"In version 8.x, the plugin factory was asynchronous; in 9.0.0 it is synchronous again.","severity":"deprecated","affected_versions":"8.x"},{"fix":"Use `path.resolve(__dirname, 'package.json')` or absolute paths to the package.json file.","message":"The `packagePath` option expects path(s) to a `package.json` file, not a directory. Incorrect paths cause the plugin to silently not externalize dependencies.","severity":"gotcha","affected_versions":">=8.0.0"},{"fix":"Use Vite's `apply: 'build'` property in the plugin options or manually check the environment.","message":"If using Vite, the plugin is not applied to the dev server; it only affects the build phase. This may cause differences in resolution between dev and build.","severity":"gotcha","affected_versions":">=8.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Replace require() with import: use `import nodeExternals from 'rollup-plugin-node-externals'` and configure your project for ESM (e.g., add \"type\": \"module\" in package.json).","cause":"Attempting to use CommonJS require() to import an ESM-only package.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/rollup-plugin-node-externals/dist/index.mjs not supported."},{"fix":"Use one of the valid values: 'add' (or true), 'strip' (or false), or 'ignore'.","cause":"Passing an invalid value to the builtinsPrefix option (e.g., a string like 'keep' or a number).","error":"rollup-plugin-node-externals: Option `builtinsPrefix` must be one of 'add', 'strip', 'ignore', true, or false."},{"fix":"Provide an absolute path to the actual package.json file: `packagePath: path.resolve(__dirname, 'package.json')`.","cause":"The packagePath option points to a non-existent file or a directory, not a package.json.","error":"rollup-plugin-node-externals: Could not find package.json at path /some/path"},{"fix":"Set `output.format` (e.g., 'cjs', 'esm', 'iife') in your Rollup config.","cause":"Using nodeExternals without setting output.format in Rollup configuration.","error":"(!) RollupOptions `output.format` must be set when not in watch mode"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}