{"id":12368,"library":"vite-plugin-commonjs","title":"Vite CommonJS Plugin","description":"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.","status":"active","version":"0.10.4","language":"javascript","source_language":"en","source_url":"https://github.com/vite-plugin/vite-plugin-commonjs","tags":["javascript","vite","plugin","commonjs","require","typescript"],"install":[{"cmd":"npm install vite-plugin-commonjs","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-commonjs","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-commonjs","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This is a Vite plugin and requires Vite to function as a peer dependency.","package":"vite","optional":false}],"imports":[{"note":"The plugin is an ESM module and must be imported using ESM syntax in your `vite.config.js` file.","wrong":"const commonjs = require('vite-plugin-commonjs')","symbol":"commonjs","correct":"import commonjs from 'vite-plugin-commonjs'"},{"note":"Use for type-checking the plugin configuration object in TypeScript-enabled Vite configurations.","symbol":"Options","correct":"import type { Options } from 'vite-plugin-commonjs'"},{"note":"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.","wrong":"import commonjs from 'vite-plugin-commonjs';\nexport default {\n  plugins: [\n    commonjs\n  ]\n}","symbol":"Configuring the plugin","correct":"import { defineConfig } from 'vite';\nimport commonjs from 'vite-plugin-commonjs';\n\nexport default defineConfig({\n  plugins: [\n    commonjs(/* options */)\n  ]\n});"}],"quickstart":{"code":"// vite.config.js\nimport { defineConfig } from 'vite'\nimport commonjs from 'vite-plugin-commonjs'\n\nexport default defineConfig({\n  plugins: [\n    commonjs({\n      // Optional: filter which modules to process. By default, node_modules are excluded.\n      // Example: Include a specific CommonJS library from node_modules\n      filter: (id) => id.includes('node_modules/my-cjs-lib') || !id.includes('node_modules'),\n      // Optional: configure dynamic require behavior\n      dynamic: {\n        loose: true, // Enable Webpack-like behavior for dynamic require expressions\n        onFiles: (files, id) => {\n          // Example: Exclude TypeScript declaration files from dynamic require resolution\n          return files.filter(f => !f.endsWith('.d.ts'))\n        }\n      },\n      // Optional: advanced configuration for import rules\n      advanced: {\n        importRules: 'default' // Can be 'namespace' or a function (id: string) => ImportType\n      }\n    }),\n  ]\n})","lang":"javascript","description":"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."},"warnings":[{"fix":"Modify your plugin configuration: `commonjs({ filter: (id) => id.includes('node_modules/your-cjs-lib') || !id.includes('node_modules') })`.","message":"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.","severity":"gotcha","affected_versions":">=0.7.0"},{"fix":"Consult the `CHANGELOG.md` on the GitHub repository for specific migration steps and updated configuration options when upgrading to a new minor version.","message":"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.","severity":"breaking","affected_versions":">=0.10.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"ReferenceError: require is not defined"},{"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.","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.","error":"Cannot read properties of undefined (reading 'default') / [vite] The 'default' export is not exported by 'module'."},{"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.","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.","error":"Error: Cann't found module: './views/foo'"}],"ecosystem":"npm"}