vite-plugin-require

1.2.17 verified Mon Apr 27 auth: no javascript

A Vite plugin that enables CommonJS require() syntax in Vite projects, converting require calls to ESM imports or import.meta.url references. Version 1.2.17 is the latest stable release, supporting Vite 2 through 6. It uses a regex-based transform to replace require() calls, with options to control file scope and conversion mode. Different from alternatives like @originjs/vite-plugin-commonjs, this plugin focuses specifically on require() transforms for asset and module references. It ships TypeScript types but has a limited API surface. Last updated in 2024, the plugin has moderate community adoption and is maintained for compatibility with newer Vite versions.

Common errors

error Error: Cannot find module 'vite-plugin-require' ↓

cause Package not installed or incorrect import path

fix

Run npm install vite-plugin-require or yarn add vite-plugin-require.

error TypeError: vitePluginRequire is not a function ↓

cause Using the plugin incorrectly on Vite 4/5 where .default() is required

fix

Replace vitePluginRequire() with vitePluginRequire.default() in your Vite config for Vite 4/5.

error [vite] Internal server error: Transform failed with 1 error: The assignment to `require` is not a valid call. ↓

cause Using template literals or dynamic expressions in require() that cannot be statically analyzed

fix

Ensure require() arguments are simple string literals or top-level variables. No template literals or complex expressions.

error Error: require() of ES Module not supported ↓

cause Trying to use require() with a file that is an ES module without default export

fix

Ensure the required module has a default export or use dynamic import() instead.

Warnings

gotcha Variables used in require() must be declared at the top of the file and cannot use template literals. ↓

fix Move require() variable declarations to top of file and avoid string templates like `${path}`.

breaking Vite 4 and 5 require using .default() method on the imported function, not direct invocation. ↓

fix Use vitePluginRequire.default() in your config for Vite 4/5. Check documentation for exact version compatibility.

gotcha Plugin must be placed after the Vue plugin (or React/other framework plugins) to work correctly. ↓

fix Reorder plugins so vitePluginRequire() comes after vue(), react(), etc.

gotcha When translateType is 'importMetaUrl', require() code is not deleted; conditional require() works but dynamic imports may not behave as expected. ↓

fix Use translateType: 'importMetaUrl' only when you need to conditionally keep require() in development, and be aware that the original source remains.

gotcha The entire project root is the root directory for require() resolution. Relative paths are resolved from the project root, not the file location. ↓

fix Use absolute paths (starting from project root) or ensure paths are correct relative to project root.

Install

npm install vite-plugin-require

yarn add vite-plugin-require

pnpm add vite-plugin-require

Imports

vitePluginRequire
wrong
```
const vitePluginRequire = require('vite-plugin-require')
```
correct
```
import vitePluginRequire from 'vite-plugin-require'
```
Package exports a default function. CommonJS require() is not recommended in ESM contexts. For Vite 4/5, use .default() as shown in docs.
default
wrong
```
vitePluginRequire()
```
correct
```
vitePluginRequire.default()
```
On Vite 4/5, the correct usage is vitePluginRequire.default() due to ESM/CJS interop. Check your Vite version to determine which pattern to use.

vitePluginRequire (with type import)

wrong

import { vitePluginRequire } from 'vite-plugin-require'

correct

import type { Plugin } from 'vite'; const vitePluginRequire = (): Plugin => import('vite-plugin-require').then(m => m.default())

The package has no named exports; only a default export is available. Use dynamic import or default import.

Quickstart

Configures Vite to use require() by adding the plugin after vue() and passing optional regex and translateType options.

// vite.config.js
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import vitePluginRequire from 'vite-plugin-require';

export default defineConfig({
  plugins: [
    vue(),
    // Must be after vue() plugin
    vitePluginRequire({
      fileRegex: /(.jsx?|.tsx?|.vue)$/,
      translateType: 'import' // 'import' or 'importMetaUrl'
    })
  ]
});
// In any .vue, .jsx, .tsx file:
const img = require('./imgs/logo.png'); // Converts to import
console.log(img);

// For Vite 4/5, use:
// import vitePluginRequire from 'vite-plugin-require';
// and in config: vitePluginRequire.default()