{"id":20668,"library":"vite-plugin-externals","title":"vite-plugin-externals","description":"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.","status":"active","version":"0.6.2","language":"javascript","source_language":"en","source_url":"https://github.com/crcong/vite-plugin-externals","tags":["javascript","vite-plugin","external","externals","typescript"],"install":[{"cmd":"npm install vite-plugin-externals","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-externals","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-externals","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency; plugin only works within Vite's plugin system","package":"vite","optional":false}],"imports":[{"note":"ESM-only package; dynamic require() will fail in ESM context, but TypeScript's esModuleInterop may mask it.","wrong":"const viteExternalsPlugin = require('vite-plugin-externals')","symbol":"viteExternalsPlugin","correct":"import { viteExternalsPlugin } from 'vite-plugin-externals'"},{"note":"There is no default export. Only named export exists.","wrong":"import viteExternalsPlugin from 'vite-plugin-externals'","symbol":"default export (none)","correct":"import { viteExternalsPlugin } from 'vite-plugin-externals'"},{"note":"Options interface is not runtime export; only exists as TypeScript type.","wrong":"import { ViteExternalsOptions } from 'vite-plugin-externals'","symbol":"type definitions","correct":"import type { ViteExternalsOptions } from 'vite-plugin-externals'"}],"quickstart":{"code":"// vite.config.js\nimport { defineConfig } from 'vite';\nimport { viteExternalsPlugin } from 'vite-plugin-externals';\n\nexport default defineConfig({\n  plugins: [\n    viteExternalsPlugin({\n      vue: 'Vue',\n      react: 'React',\n      'react-dom': 'ReactDOM',\n      lazy: ['React', 'lazy']\n    }, {\n      disableInServe: true,\n      useWindow: true,\n      filter: (code, id, ssr) => {\n        // Exclude node_modules and non-js files\n        if (id.includes('node_modules')) return false;\n        if (!/\\.[jt]sx?$/.test(id)) return false;\n        return true;\n      }\n    })\n  ]\n});","lang":"javascript","description":"Configures vite-plugin-externals to replace Vue, React, ReactDOM, and nested lazy imports with global window lookups, disabling in dev mode to preserve HMR."},"warnings":[{"fix":"Ensure viteExternalsPlugin is listed after Vue/Svelte/etc. plugins in the plugins array.","message":"Plugin must be placed after SFC transformers (e.g., @vitejs/plugin-vue) because it only operates on JavaScript code, not raw SFC files.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Override the filter option to return true for node_modules paths.","message":"By 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.","severity":"breaking","affected_versions":">=0.2.0"},{"fix":"Set disableInServe: true or load development versions during serve.","message":"Using production builds of libraries (e.g., vue.global.prod.js) in dev mode can break HMR. The plugin does not automatically detect this.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Keep useWindow: true (default) or avoid modules with slashes.","message":"Special characters in module names (e.g., '@scope/pkg') cause runtime errors when useWindow is false, because the variable name would be invalid.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Upgrade to >=0.5.0 or adjust filter to ignore the ssr argument.","message":"The filter callback signature does not include a third argument in older versions (before 0.5). Check version compatibility if using SSR.","severity":"deprecated","affected_versions":"<0.5.0"},{"fix":"For SSR, use separate configuration (e.g., disable the plugin or handle externals via Rollup options).","message":"Plugin does not work for SSR or CJS environments by default; only transforms ESM-like imports for browser usage.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run 'npm install vite-plugin-externals --save-dev' and ensure your project is ESM (package.json has \"type\": \"module\" or use .mjs files).","cause":"Package not installed or ESM-only import used in CJS context without proper module resolution.","error":"Cannot find module 'vite-plugin-externals'"},{"fix":"Ensure you only call viteExternalsPlugin() once in the plugins list.","cause":"Multiple instances of the plugin in the same plugins array.","error":"The plugin 'vite:externals' has been applied twice."},{"fix":"Reorder plugins so that viteExternalsPlugin comes after @vitejs/plugin-vue.","cause":"Plugin is transforming files before SFC compilation (e.g., .vue files still contain template code).","error":"Unexpected token: keyword 'const'"},{"fix":"Disable the plugin for SSR or set useWindow: false (but only if module names have no special characters).","cause":"The transformed code references window, which is not available in SSR/Node environments.","error":"window is not defined"},{"fix":"Check that the keys in viteExternalsPlugin options exactly match the import source string (e.g., 'react' not 'React').","cause":"Externals mapping is missing or incorrectly configured, so the import is not replaced.","error":"Uncaught TypeError: Failed to resolve module specifier 'react'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}