Vite CommonJS Plugin

0.10.4 · active · verified Sun Apr 19

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.

Common errors

```
ReferenceError: require is not defined
```
cause 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'.
```
cause 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'
```
cause 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.

Warnings

gotcha By 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') })`.
breaking Minor 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.
gotcha While `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.

Install

npm install vite-plugin-commonjs npm
yarn add vite-plugin-commonjs yarn
pnpm add vite-plugin-commonjs pnpm

Imports

commonjs
wrong:
```
const commonjs = require('vite-plugin-commonjs')
```
correct:
```
import commonjs from '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

wrong:

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

correct:

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

export default defineConfig({
  plugins: [
    commonjs(/* options */)
  ]
});

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.

Quickstart

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

view raw JSON →