Registry / web-framework / vite-plugin-externals

vite-plugin-externals

library0.6.2jsnpmunverified

A Vite plugin that converts import statements into global variable lookups (window['Lib']), replicating Webpack's externals functionality for production builds. Version 0.6.2 requires Vite >=2.0.0 and Node ^14.18.0 || >=16.0.0. Unlike manual Rollup externals, this plugin transforms source code at the JS level, preserving static analysis. Released under MIT, with occasional updates. Key differentiator: supports deeply chained global paths (e.g., window['React']['lazy']) and works on JSX/TSX files after SFC transformation. Does not affect SSR by default; CJS/SSR users need separate handling.

web-framework

npm install vite-plugin-externals

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-EXTERN

vite-plugin-externals

web-frameworkjavascriptv0.6.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

viteExternalsPlugin

✓ import { viteExternalsPlugin } from 'vite-plugin-externals'

✗ const viteExternalsPlugin = require('vite-plugin-externals')

ESM-only package; dynamic require() will fail in ESM context, but TypeScript's esModuleInterop may mask it.

default export (none)

✓ import { viteExternalsPlugin } from 'vite-plugin-externals'

✗ import viteExternalsPlugin from 'vite-plugin-externals'

There is no default export. Only named export exists.

type definitions

✓ import type { ViteExternalsOptions } from 'vite-plugin-externals'

✗ import { ViteExternalsOptions } from 'vite-plugin-externals'

Options interface is not runtime export; only exists as TypeScript type.

Configures vite-plugin-externals to replace Vue, React, ReactDOM, and nested lazy imports with global window lookups, disabling in dev mode to preserve HMR.

// vite.config.js import { defineConfig } from 'vite'; import { viteExternalsPlugin } from 'vite-plugin-externals'; export default defineConfig({ plugins: [ viteExternalsPlugin({ vue: 'Vue', react: 'React', 'react-dom': 'ReactDOM', lazy: ['React', 'lazy'] }, { disableInServe: true, useWindow: true, filter: (code, id, ssr) => { // Exclude node_modules and non-js files if (id.includes('node_modules')) return false; if (!/\.[jt]sx?$/.test(id)) return false; return true; } }) ] });

Debug

Known issues

gotchaPlugin must be placed after SFC transformers (e.g., @vitejs/plugin-vue) because it only operates on JavaScript code, not raw SFC files.

fix

Ensure viteExternalsPlugin is listed after Vue/Svelte/etc. plugins in the plugins array.

affects: >=0.1.0

breakingBy default, the plugin does not transform files in node_modules. If you need to externals from node_modules, you must provide a custom filter function.

fix

Override the filter option to return true for node_modules paths.

affects: >=0.2.0

gotchaUsing production builds of libraries (e.g., vue.global.prod.js) in dev mode can break HMR. The plugin does not automatically detect this.

fix

Set disableInServe: true or load development versions during serve.

affects: >=0.1.0

gotchaSpecial characters in module names (e.g., '@scope/pkg') cause runtime errors when useWindow is false, because the variable name would be invalid.

fix

Keep useWindow: true (default) or avoid modules with slashes.

affects: >=0.1.0

deprecatedThe filter callback signature does not include a third argument in older versions (before 0.5). Check version compatibility if using SSR.

fix

Upgrade to >=0.5.0 or adjust filter to ignore the ssr argument.

affects: <0.5.0

gotchaPlugin does not work for SSR or CJS environments by default; only transforms ESM-like imports for browser usage.

fix

For SSR, use separate configuration (e.g., disable the plugin or handle externals via Rollup options).

affects: >=0.1.0

Errors

Common errors & fixes

Cannot find module 'vite-plugin-externals'

Package not installed or ESM-only import used in CJS context without proper module resolution.

fix

Run 'npm install vite-plugin-externals --save-dev' and ensure your project is ESM (package.json has "type": "module" or use .mjs files).

The plugin 'vite:externals' has been applied twice.

Multiple instances of the plugin in the same plugins array.

fix

Ensure you only call viteExternalsPlugin() once in the plugins list.

Unexpected token: keyword 'const'

Plugin is transforming files before SFC compilation (e.g., .vue files still contain template code).

fix

Reorder plugins so that viteExternalsPlugin comes after @vitejs/plugin-vue.

window is not defined

The transformed code references window, which is not available in SSR/Node environments.

fix

Disable the plugin for SSR or set useWindow: false (but only if module names have no special characters).

Uncaught TypeError: Failed to resolve module specifier 'react'

Externals mapping is missing or incorrectly configured, so the import is not replaced.

fix

Check that the keys in viteExternalsPlugin options exactly match the import source string (e.g., 'react' not 'React').

Upgrade

Version history

0.6.2latest on npm

Audit

Dependencies

viterequiredpeer dependency; plugin only works within Vite's plugin system

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/crcong/vite-plugin-externals ↗

packagehttps://www.npmjs.com/package/vite-plugin-externals ↗