Registry / web-framework / vite-plugin-commonjs

vite-plugin-commonjs

library0.10.4jsnpmunverified

This package, `vite-plugin-commonjs`, provides a pure JavaScript implementation to process CommonJS modules within a Vite build. It enables Vite to correctly handle `require` statements, `module.exports`, and `exports` patterns often found in legacy or Node.js-focused libraries that haven't transitioned to ESM. The current stable version is 0.10.4, with frequent minor updates indicating active development and maintenance, often incorporating community contributions. Key differentiators include robust support for dynamic `require` expressions, similar to Webpack's behavior, and explicit handling for `node_modules` and aliases, which are often problematic when migrating CommonJS-heavy projects to Vite's ESM-first approach. It ships with TypeScript types for improved development experience.

web-framework

npm install vite-plugin-commonjs

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-COMMON

vite-plugin-commonjs

web-frameworkjavascriptv0.10.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–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

commonjs

✓ import commonjs from 'vite-plugin-commonjs'

✗ const commonjs = require('vite-plugin-commonjs')

The plugin is an ESM module and must be imported using ESM syntax in your `vite.config.js` file.

Options

✓ import type { Options } from 'vite-plugin-commonjs'

Use for type-checking the plugin configuration object in TypeScript-enabled Vite configurations.

Configuring the plugin

✓ import { defineConfig } from 'vite'; import commonjs from 'vite-plugin-commonjs'; export default defineConfig({ plugins: [ commonjs(/* options */) ] });

✗ import commonjs from 'vite-plugin-commonjs'; export default { plugins: [ commonjs ] }

The `commonjs` import is a function that returns the plugin object; it must be called (even with no options) when added to Vite's plugins array.

This quickstart demonstrates how to integrate `vite-plugin-commonjs` into a Vite project's configuration, showing basic options for filtering modules, handling dynamic `require`, and advanced import rules.

// vite.config.js import { defineConfig } from 'vite' import commonjs from 'vite-plugin-commonjs' export default defineConfig({ plugins: [ commonjs({ // Optional: filter which modules to process. By default, node_modules are excluded. // Example: Include a specific CommonJS library from node_modules filter: (id) => id.includes('node_modules/my-cjs-lib') || !id.includes('node_modules'), // Optional: configure dynamic require behavior dynamic: { loose: true, // Enable Webpack-like behavior for dynamic require expressions onFiles: (files, id) => { // Example: Exclude TypeScript declaration files from dynamic require resolution return files.filter(f => !f.endsWith('.d.ts')) } }, // Optional: advanced configuration for import rules advanced: { importRules: 'default' // Can be 'namespace' or a function (id: string) => ImportType } }), ] })

Debug

Known issues

gotchaBy default, `vite-plugin-commonjs` explicitly excludes files within `node_modules` from transformation. To process CommonJS packages installed as dependencies, you must use the `filter` option to explicitly include them.

fix

Modify your plugin configuration: `commonjs({ filter: (id) => id.includes('node_modules/your-cjs-lib') || !id.includes('node_modules') })`.

affects: >=0.7.0

breakingMinor versions of `vite-plugin-commonjs`, particularly from 0.10.0 onwards, may introduce changes to internal CommonJS transformation logic or options. Always review the `CHANGELOG.md` when upgrading to avoid unexpected build issues.

fix

Consult the `CHANGELOG.md` on the GitHub repository for specific migration steps and updated configuration options when upgrading to a new minor version.

affects: >=0.10.0

gotchaWhile `vite-plugin-commonjs` aims to handle complex CommonJS patterns, some highly idiosyncratic modules (e.g., those heavily relying on `this` context or global mutations) might not translate perfectly to ESM. This can lead to runtime errors.

fix

For problematic dependencies, consider using Vite's `optimizeDeps.exclude` to let Vite pre-bundle them without plugin intervention, or manually inspect the transformed output to pinpoint and address the specific issue.

affects: >=0.1.0

Errors

Common errors & fixes

ReferenceError: require is not defined

A `require` statement is being executed in an environment (like the browser or a pure ESM context) where it's not natively supported, and `vite-plugin-commonjs` either didn't process the file or failed to transform it.

fix

Ensure `vite-plugin-commonjs` is correctly installed, configured in `vite.config.js`, and that the file containing the `require` statement is not inadvertently excluded by the plugin's `filter` option or Vite's build process. Restart Vite's development server.

Cannot read properties of undefined (reading 'default') / [vite] The 'default' export is not exported by 'module'.

This typically occurs when a CommonJS module is exported via `module.exports = ...` (a default export in CJS terms) but is being imported as a named export in ESM, or vice-versa. The plugin's transformation might be misinterpreting the export type.

fix

If the CJS module uses `module.exports = value`, try `import value from 'module-name'`. If it uses `exports.foo = value`, try `import { foo } from 'module-name'`. If issues persist, check the `advanced.importRules` option.

Error: Cann't found module: './views/foo'

A dynamic `require('./path/' + variable)` expression failed to resolve all possible modules at build time, either because not all possible paths were detectable or the `dynamic` option was not configured correctly.

fix

Ensure the `dynamic` option is enabled in the plugin configuration, especially `dynamic.loose: true` for broader compatibility. Verify that all potential paths for dynamic `require` are accessible and resolvable by Vite.

Upgrade

Version history

0.10.4latest on npm

Audit

Dependencies

viterequiredThis is a Vite plugin and requires Vite to function as a peer dependency.

Agent activity

5 hits · last 30 days

node

OpenAI (training)

Resources

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

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

homepagehttps://vite-plugin-commonjs.netlify.app ↗