vite-plugin-externalize-deps

0.10.0 verified Mon Apr 27 auth: no javascript

A Vite plugin that automatically externalizes dependencies from your bundle during build, including subpath patterns. Current stable version is 0.10.0, released 2024-12-15. Supports Vite 2 through 7. Key differentiators: handles subpath exports, provides fine-grained control over which dependencies are externalized (deps, devDeps, peerDeps, optionalDeps, nodeBuiltins), and allows both inclusion and exception patterns via strings or regexes.

Common errors

error Cannot find module 'vite-plugin-externalize-deps' ↓

cause Package not installed or missing from node_modules.

fix

Install the package as a dev dependency: npm install --save-dev vite-plugin-externalize-deps

error [vite] RollupError: "externalizeDeps" is not exported by "node_modules/vite-plugin-externalize-deps/dist/index.mjs" ↓

cause Using default import instead of named import.

fix

Use import { externalizeDeps } from 'vite-plugin-externalize-deps' (curly braces).

error TypeError: externalizeDeps is not a function ↓

cause Calling `new externalizeDeps()` or using it as a constructor.

fix

Remove new and call as externalizeDeps() directly.

error Error: The 'except' option requires an array of strings or RegExp. ↓

cause Passed a non-array value to 'except' (e.g., a string or object).

fix

Ensure except is an array: except: ['package-name'].

Warnings

breaking Before v0.5.0, only Vite 2 and 3 were supported; Vite 4 support added in v0.5.0. ↓

fix Upgrade plugin to v0.5.0 or later for Vite 4 compatibility, or use an older Vite.

breaking Before v0.8.0, Vite 5 was not supported; Vite 5 support added in v0.8.0. ↓

fix Upgrade to v0.8.0+ for Vite 5.

breaking Before v0.9.0, Vite 6 was not supported; Vite 6 support added in v0.9.0. ↓

fix Upgrade to v0.9.0+ for Vite 6.

breaking Before v0.10.0, Vite 7 was not supported; Vite 7 support added in v0.10.0. ↓

fix Upgrade to v0.10.0+ for Vite 7.

gotcha The `devDeps` option defaults to `false`, so development dependencies are NOT externalized by default. This can cause them to be bundled, which may be unexpected if you want to externalize them as well. ↓

fix Set `devDeps: true` in the plugin options to externalize devDependencies.

gotcha The `except` option only works for dependencies that would otherwise be externalized. It does not enable externalization of packages not in the plugin's scope (e.g., if a package is not in any of `deps`, `peerDeps`, etc., using `except` has no effect). ↓

fix Use the `include` option (added in v0.7.0) to add packages to be externalized that are not automatically detected.

deprecated The `useFile` option is deprecated in favor of automatic package.json detection. It still works but may be removed in a future major version. ↓

fix Omit `useFile` to let the plugin find package.json automatically, or keep it if you need a custom path.

Install

npm install vite-plugin-externalize-deps

yarn add vite-plugin-externalize-deps

pnpm add vite-plugin-externalize-deps

Imports

externalizeDeps

wrong

import externalizeDeps from 'vite-plugin-externalize-deps'

correct

import { externalizeDeps } from 'vite-plugin-externalize-deps'

Named export only; no default export available.

VitePluginExternalizeDeps

wrong

import { VitePluginExternalizeDeps } from 'vite-plugin-externalize-deps'

correct

import type { VitePluginExternalizeDeps } from 'vite-plugin-externalize-deps'

Type export only. Do not import as value.

externalizeDeps

wrong

const externalizeDeps = require('vite-plugin-externalize-deps')

correct

const { externalizeDeps } = require('vite-plugin-externalize-deps')

CJS requires destructuring because it's a named export.

Quickstart

Add the plugin to vite.config.ts with default options. Externalizes all dependencies, peerDeps, optionalDeps, and node builtins; devDeps are bundled by default.

import { defineConfig } from 'vite';
import { externalizeDeps } from 'vite-plugin-externalize-deps';

export default defineConfig({
  plugins: [
    externalizeDeps({
      // Defaults shown:
      deps: true,
      devDeps: false,
      except: [],
      nodeBuiltins: true,
      optionalDeps: true,
      peerDeps: true,
      useFile: '/path/to/package.json',
    }),
  ],
});