Registry / web-framework / vite-plugin-commonjs-externals

vite-plugin-commonjs-externals

library0.1.4jsnpmunverified

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.

web-framework devops serialization

npm install vite-plugin-commonjs-externals

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-COMMON

vite-plugin-commonjs-externals

web-frameworkjavascriptv0.1.4

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–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

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

default

✓ import commonjsExternals from 'vite-plugin-commonjs-externals'

✗ const commonjsExternals = require('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

✓ import { presets } from 'vite-plugin-commonjs-externals'

✗ import presets from 'vite-plugin-commonjs-externals/presets'

presets is a named export, not a subpath export. It provides common externals like electron, node builtins.

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 })], });

Debug

Known issues

gotchaYou 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.

affects: >=0.0.0

gotchaThe 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().

affects: >=0.0.0

gotchaThe 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.

affects: >=0.0.0

gotchaWhen 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.

affects: >=0.0.0

Errors

Common errors & fixes

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

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: Could not resolve 'electron' (or similar external) from '...'

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.

TypeError: commonjsExternals is not a function

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).

Upgrade

Version history

0.1.4latest on npm

Audit

Dependencies

viterequiredpeer dependency; plugin only works with Vite >=4.3.9 || ^5.0.0

Agent activity

17 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/xiaoxiangmoe/vite-plugin-commonjs-externals ↗

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