vite-plugin-require-transform

1.0.21 verified Mon Apr 27 auth: no javascript

A Vite plugin that converts CommonJS require() calls to ES module import syntax at build time, enabling codebases that use require() to work with Vite's ESM-native dev server. Current stable version: 1.0.21. Released as needed, with occasional minor updates. Key differentiators: supports complex cases like ternary expressions, method calls on require results, and custom import path handlers; does not require source code changes; filters by file regex (default .ts/.tsx) to avoid unnecessary transformations. Alternatives like @originjs/vite-plugin-commonjs or vite-plugin-commonjs-externals may handle broader CJS interop, but this plugin is minimal and focused specifically on require → import.

Common errors

error SyntaxError: Unexpected token '.' (or similar parsing errors) ↓

cause Plugin tries to transform require inside nested expressions it cannot handle (e.g., require('x').y.z).

fix

Rewrite to const x = require('x'); x.y.z; or use importPathHandler to simplify the expression.

error Error: The plugin 'vite-plugin-require-transform' doesn't seem to be a valid Vite plugin. ↓

cause Importing the plugin incorrectly (e.g., as named export instead of default).

fix

Use 'import requireTransform from 'vite-plugin-require-transform''.

error Uncaught ReferenceError: require is not defined ↓

cause Plugin did not transform the file (file not matching regex or plugin not added).

fix

Check that fileRegex includes the file's extension and that plugin is in the plugins array.

Warnings

breaking Dynamic require() (e.g., require(variable)) is not supported and will throw at runtime. ↓

fix Replace dynamic require() with dynamic import() or static import.

gotcha Transformation only applies to files matching fileRegex (default .ts/.tsx). JS files are ignored unless you set fileRegex to include them. ↓

fix Explicitly set fileRegex: /\.(js|ts|jsx|tsx)$/ in plugin options.

gotcha When require is used with a ternary or conditional, the resulting import may produce named exports that don't exist, causing runtime errors. ↓

fix Assign require() result to a const even in conditional branches to ensure correct import extraction.

deprecated No known deprecated patterns yet; package is still actively maintained.

Install

npm install vite-plugin-require-transform

yarn add vite-plugin-require-transform

pnpm add vite-plugin-require-transform

Imports

default (requireTransform)
wrong
```
const requireTransform = require('vite-plugin-require-transform')
```
correct
```
import requireTransform from 'vite-plugin-require-transform'
```
Package exports a CommonJS default export via ESM wrapper; named import { requireTransform } will not work.

VitePluginRequireTransformParamsType

wrong

import { VitePluginRequireTransformParamsType } from 'vite-plugin-require-transform'

correct

import type { VitePluginRequireTransformParamsType } from 'vite-plugin-require-transform'

TypeScript type only; not available at runtime. Use 'import type' to avoid bundling issues.

plugin usage in vite.config.ts
wrong
```
plugins: [requireTransform()]
```
correct
```
plugins: [requireTransform({ fileRegex: /.[jt]sx?$/ })]
```
Without options, default fileRegex matches .ts and .tsx only; for JavaScript or other files you must override.

Quickstart

Basic configuration of vite-plugin-require-transform in vite.config.ts, showing all available options with default overrides.

// vite.config.ts
import { defineConfig } from 'vite';
import requireTransform from 'vite-plugin-require-transform';

export default defineConfig({
  plugins: [
    requireTransform({
      fileRegex: /\.(js|ts|jsx|tsx)$/,
      importPrefix: '__req_',
      importPathHandler: (path: string) => path.replace(/\?.*$/, '')
    })
  ]
});