{"id":22613,"library":"vite-plugin-commonjs-externals","title":"vite-plugin-commonjs-externals","description":"Vite plugin that prevents bundling of specified ESM imports and replaces them with CommonJS require() calls at runtime. Version 0.1.4, stable with infrequent releases. Designed for Electron renderer processes and Node.js environments where CommonJS modules (like 'electron', 'fs', 'path') must be imported via require() rather than bundled. Key differentiator: handles named, default, and namespace imports correctly by generating interop code similar to Rollup's CJS output. Unlike @vitejs/plugin-commonjs which focuses on converting CJS to ESM, this plugin does the reverse — converting ESM imports into CJS requires for a list of externals. Supports regex patterns for dynamic package matching.","status":"active","version":"0.1.4","language":"javascript","source_language":"en","source_url":"https://github.com/xiaoxiangmoe/vite-plugin-commonjs-externals","tags":["javascript","vite-plugin","commonjs"],"install":[{"cmd":"npm install vite-plugin-commonjs-externals","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-commonjs-externals","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-commonjs-externals","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency; plugin only works with Vite >=4.3.9 || ^5.0.0","package":"vite","optional":false}],"imports":[{"note":"ESM-only package; does not export a CommonJS module. Named export is also available as 'vite-plugin-commonjs-externals/presets'.","wrong":"const commonjsExternals = require('vite-plugin-commonjs-externals')","symbol":"default","correct":"import commonjsExternals from 'vite-plugin-commonjs-externals'"},{"note":"The package has a default export that is a function; you can name it anything.","symbol":"commonjsExternals","correct":"import commonjsExternals from 'vite-plugin-commonjs-externals'"},{"note":"presets is a named export, not a subpath export. It provides common externals like electron, node builtins.","wrong":"import presets from 'vite-plugin-commonjs-externals/presets'","symbol":"presets","correct":"import { presets } from 'vite-plugin-commonjs-externals'"}],"quickstart":{"code":"import { defineConfig } from 'vite';\nimport commonjsExternals from 'vite-plugin-commonjs-externals';\n\nconst externals = ['path', /^electron(\\/.+)?$/];\n\nexport default defineConfig({\n  optimizeDeps: {\n    exclude: externals,\n  },\n  plugins: [commonjsExternals({ externals })],\n});","lang":"typescript","description":"Configures Vite to treat 'path' and 'electron' packages as CommonJS externals, preventing them from being bundled."},"warnings":[{"fix":"Always include the same list in optimizeDeps.exclude as shown in the quickstart.","message":"You must also add the externals to optimizeDeps.exclude, otherwise Vite may try to pre-bundle them and fail.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Ensure external packages are imported with static import statements, not require().","message":"The plugin only transforms ESM imports (import ... from '...'), not dynamic imports or require() calls. If your code uses require(), it will be left untouched.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Do not use this plugin in SSR configurations; use Vite's built-in SSR externals instead.","message":"The plugin does not work with Vite's SSR mode; it's intended for renderer processes in Electron or similar browser-like environments.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Add type stubs or set 'skipLibCheck: true' in tsconfig.json.","message":"When using TypeScript, you might get type errors on the externals because the require-generated modules do not have type declarations. Use 'declare module' or skipLibCheck.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Upgrade Vite to ^4.3.9 or ^5.0.0 which are known to work.","cause":"Using an older version of Vite that does not support the hook names used by this plugin.","error":"Error: The plugin \"commonjs-externals\" has unknown hooks: \"renderChunk\""},{"fix":"Add the package to optimizeDeps.exclude in vite.config.js.","cause":"The external was not listed in optimizeDeps.exclude, causing Vite to try to pre-bundle it and fail.","error":"Error: Could not resolve 'electron' (or similar external) from '...'"},{"fix":"Use import commonjsExternals from 'vite-plugin-commonjs-externals' (ESM default import).","cause":"Importing the plugin incorrectly, e.g., using require() or importing named export instead of default.","error":"TypeError: commonjsExternals is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}