vite-plugin-commonjs-externals

0.1.4 verified Mon Apr 27 auth: no javascript

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.

Common errors

error Error: The plugin "commonjs-externals" has unknown hooks: "renderChunk" ↓

cause Using an older version of Vite that does not support the hook names used by this plugin.

fix

Upgrade Vite to ^4.3.9 or ^5.0.0 which are known to work.

error Error: Could not resolve 'electron' (or similar external) from '...' ↓

cause The external was not listed in optimizeDeps.exclude, causing Vite to try to pre-bundle it and fail.

fix

Add the package to optimizeDeps.exclude in vite.config.js.

error TypeError: commonjsExternals is not a function ↓

cause Importing the plugin incorrectly, e.g., using require() or importing named export instead of default.

fix

Use import commonjsExternals from 'vite-plugin-commonjs-externals' (ESM default import).

Warnings

gotcha You must also add the externals to optimizeDeps.exclude, otherwise Vite may try to pre-bundle them and fail. ↓

fix Always include the same list in optimizeDeps.exclude as shown in the quickstart.

gotcha The plugin only transforms ESM imports (import ... from '...'), not dynamic imports or require() calls. If your code uses require(), it will be left untouched. ↓

fix Ensure external packages are imported with static import statements, not require().

gotcha The plugin does not work with Vite's SSR mode; it's intended for renderer processes in Electron or similar browser-like environments. ↓

fix Do not use this plugin in SSR configurations; use Vite's built-in SSR externals instead.

gotcha 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. ↓

fix Add type stubs or set 'skipLibCheck: true' in tsconfig.json.

Install

npm install vite-plugin-commonjs-externals

yarn add vite-plugin-commonjs-externals

pnpm add vite-plugin-commonjs-externals

Imports

default
wrong
```
const commonjsExternals = require('vite-plugin-commonjs-externals')
```
correct
```
import commonjsExternals from 'vite-plugin-commonjs-externals'
```
ESM-only package; does not export a CommonJS module. Named export is also available as 'vite-plugin-commonjs-externals/presets'.
commonjsExternals
```
import commonjsExternals from 'vite-plugin-commonjs-externals'
```
The package has a default export that is a function; you can name it anything.
presets
wrong
```
import presets from 'vite-plugin-commonjs-externals/presets'
```
correct
```
import { presets } from 'vite-plugin-commonjs-externals'
```
presets is a named export, not a subpath export. It provides common externals like electron, node builtins.

Quickstart

Configures Vite to treat 'path' and 'electron' packages as CommonJS externals, preventing them from being bundled.

import { defineConfig } from 'vite';
import commonjsExternals from 'vite-plugin-commonjs-externals';

const externals = ['path', /^electron(\/.+)?$/];

export default defineConfig({
  optimizeDeps: {
    exclude: externals,
  },
  plugins: [commonjsExternals({ externals })],
});