vite-plugin-externalize-dependencies

1.0.1 verified Mon Apr 27 auth: no javascript

A Vite plugin (v1.0.1) that allows you to exclude specific dependencies from the Vite bundle during development. It supports externalizing by exact module name, regex, or custom function, and automatically externalizes all subexports (e.g., react/jsx-runtime when 'react' is externalized). It also suppresses common Vite errors/warnings from externalized modules. The plugin is intended for development only; for production, users should configure build.rollupOptions.external manually. It ships TypeScript types and is actively maintained with regular releases.

Common errors

error Cannot find module 'vite-plugin-externalize-dependencies' or its corresponding type declarations ↓

cause Missing installation or incorrect TypeScript configuration.

fix

Run npm i vite-plugin-externalize-dependencies --save-dev and ensure your tsconfig includes 'node_modules/@types'.

error The requested module 'vite-plugin-externalize-dependencies' does not provide an export named 'externalize' ↓

cause Trying to import a named export instead of default export.

fix

Use default import: import externalize from 'vite-plugin-externalize-dependencies'

error TypeError: externalize is not a function ↓

cause If using CommonJS via require and destructuring, externalize might be undefined.

fix

Use const externalize = require('vite-plugin-externalize-dependencies') without destructuring.

error Warning: The entry point 'moduleName' cannot be marked as external ↓

cause This warning is intentionally suppressed by the plugin; it's not an error. If you see it, the plugin may not be loaded or working.

fix

Ensure the plugin is added to the Vite plugins array and that the module is in the externals list.

Warnings

breaking Since v1.0.0, the plugin now accounts for Vite's base path config, which may change the externalized module's URL in the browser. ↓

fix Ensure your project uses Vite's base path correctly; the plugin will prepend it to externalized module requests.

gotcha The plugin is designed for development only. In production, you must manually configure build.rollupOptions.external in Vite; this plugin does not handle production builds. ↓

fix For production builds, add externalized modules to build.rollupOptions.external in your Vite config.

breaking Since v0.11.0, the plugin automatically externalizes all subexports of a module when the module name is matched by exact string. For example, externalizing 'react' now also externalizes 'react/jsx-runtime'. ↓

fix If you only want to externalize the exact module and not its subexports, use a custom function to filter subexports.

gotcha The plugin suppresses certain Vite errors/warnings for externalized modules (e.g., 'cannot be marked as external'). If you see unexpected missing dependencies, check that the module is correctly externalized. ↓

fix Verify the externals list; if a module is incorrectly externalized, it will not be bundled. Use the plugin's logging if available.

Install

npm install vite-plugin-externalize-dependencies

yarn add vite-plugin-externalize-dependencies

pnpm add vite-plugin-externalize-dependencies

Imports

externalize

wrong

import { externalize } from 'vite-plugin-externalize-dependencies'

correct

import externalize from 'vite-plugin-externalize-dependencies'

Default export; named import will result in undefined.

ExternalizeOptions

wrong

import { ExternalizeOptions } from 'vite-plugin-externalize-dependencies'

correct

import type { ExternalizeOptions } from 'vite-plugin-externalize-dependencies'

Type-only export for TypeScript.

externalize (CommonJS)

wrong

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

correct

const externalize = require('vite-plugin-externalize-dependencies')

Default CommonJS export; destructuring fails.

Quickstart

Basic setup: import default function, pass externals array with name, regex, and function matchers.

// vite.config.ts
import { defineConfig } from 'vite';
export default defineConfig({
  plugins: [
    externalize({
      externals: [
        'react',
        /^external-.*/,
        (moduleName) => moduleName.includes('external'),
      ],
    }),
  ],
});

// Import function
import externalize from 'vite-plugin-externalize-dependencies';