vite-plugin-cjs-interop

3.3.0 verified Mon Apr 27 auth: no javascript

A Vite plugin that unwraps default imports from CommonJS (CJS) dependencies during SSR, solving the issue where CJS modules with both default and named exports require accessing the default via .default in ESM. Version 3.3.0 is current, with recent releases every few months. It works around Vite's SSR hoisting bug (vite#22122) and supports Vite 6.4–8. Automatically transforms import statements so that default imports work seamlessly in SSR, and handles dynamic imports to allow both ESM namespace and CJS direct property access. Competes with vite-plugin-commonjs but focuses specifically on default interop during SSR. ESM-only since v3 headless.

Common errors

error TypeError: Cannot read properties of undefined (reading 'default') ↓

cause CJS dependency's default export is not being unwrapped because the package is not listed in the interop dependencies.

fix

Add the package name to the cjsInterop({ dependencies: ['your-package'] }) configuration.

error ERR_REQUIRE_ESM: require() of ES Module /node_modules/vite-plugin-cjs-interop/dist/index.js from ... not supported. ↓

cause Using require() to load the plugin, but it's ESM-only since v3.

fix

Use ESM imports (import { cjsInterop } from 'vite-plugin-cjs-interop') or downgrade to v2.x.

error Uncaught TypeError: default_1.default is not a function ↓

cause A CJS dependency's default export is being accessed as .default.default due to double wrapping.

fix

Ensure the package is correctly listed in cjsInterop dependencies, and avoid manually accessing .default on the import.

Warnings

breaking v3.0.0 dropped CommonJS release; package is now ESM-only. ↓

fix Use ESM imports (import) instead of require(). If you must use CommonJS, stay on v2.x.

breaking v3.0.0 dropped support for older Vite versions (requires ~6.4 || ~7.3 || 8). ↓

fix Upgrade Vite to a supported version (6.4+, 7.3+, or 8).

gotcha dependencies option requires explicit listing of deep imports; globs are supported but must be correctly configured. ↓

fix Ensure deep imports like 'pkg/subpath' are listed separately, or use a glob pattern like 'pkg/**'.

gotcha The plugin does not transform CJS dependencies that are not listed in the 'dependencies' option. ↓

fix Make sure every CJS dependency that needs default interop is included in the dependencies array.

deprecated No known deprecations yet.

Install

npm install vite-plugin-cjs-interop

yarn add vite-plugin-cjs-interop

pnpm add vite-plugin-cjs-interop

Imports

cjsInterop
wrong
```
const cjsInterop = require('vite-plugin-cjs-interop')
```
correct
```
import { cjsInterop } from 'vite-plugin-cjs-interop'
```
Package is ESM-only since v3 (no CommonJS release). require() will fail unless using a bundler that can handle ESM.
default (cjsInterop)
wrong
```
import cjsInterop from 'vite-plugin-cjs-interop'
```
correct
```
import { cjsInterop } from 'vite-plugin-cjs-interop'
```
The package exports a named export `cjsInterop`, not a default export. Using default import will result in undefined.
Type (CjsInteropOptions)
wrong
```
import { CjsInteropOptions } from 'vite-plugin-cjs-interop'
```
correct
```
import type { CjsInteropOptions } from 'vite-plugin-cjs-interop'
```
Options type is exported but only available as a type import. Using a value import will cause a runtime error.

Quickstart

Shows how to import, configure, and add the plugin to a Vite config, listing CJS dependencies that need interop.

import { defineConfig } from 'vite';
import { cjsInterop } from 'vite-plugin-cjs-interop';

export default defineConfig({
  plugins: [
    cjsInterop({
      dependencies: [
        'some-cjs-package',
        'another-package/deep',
        '@scope/**',
      ],
    }),
  ],
});