vite-plugin-optimizer

1.4.3 verified Mon Apr 27 auth: no javascript

A Vite plugin that provides manual pre-bundling of dependencies, allowing developers to define custom code or aliased modules to replace imported packages during Vite's dependency pre-bundling phase. Version 1.4.3 is the latest stable release. It supports Browser, Node.js, and Electron environments, and offers flexible entry configurations including string code, result descriptions with alias rules, and async functions. Key differentiators: fine-grained control over pre-bundling (unlike automatic pre-bundling), compatibility with CommonJS and ESM, and ability to replace modules with custom implementations (e.g., using global variables or local files).

Common errors

error require is not defined in ES module scope (vite-plugin-optimizer default export is not a function) ↓

cause Using CommonJS `require` to import the ESM-only package.

fix

Change to ES module import: import optimizer from 'vite-plugin-optimizer'.

error Cannot find module 'vite-plugin-optimizer' or its corresponding type declarations. ↓

cause Missing installation or TypeScript configuration.

fix

Run npm i vite-plugin-optimizer -D and ensure tsconfig.json includes moduleResolution: 'node' and esModuleInterop: true.

error Plugin returned an object with 'alias' property that is not in resolve.alias format ↓

cause The `alias` property in `ResultDescription` must have `find` and `replacement`; missing one.

fix

Ensure ResultDescription.alias includes both find (string/RegExp) and replacement (string).

Warnings

gotcha Using a function with no return value (void) will skip alias registration; you must explicitly return an alias object. ↓

fix Return an object with `alias` property from the function, or return a string for code.

gotcha Modules defined in optimizer entries are automatically added to `optimizeDeps.exclude`. To pre-bundle them instead, add them to `optimizeDeps.include`. ↓

fix Add the module id to `optimizeDeps.include` if you want Vite to pre-bundle it anyway.

breaking In v1.x, the `dir` option default changed to `.vite-plugin-optimizer` (with a leading dot) to avoid conflicts with other plugins. Older versions used a different default. ↓

fix No action needed unless you relied on the old default path; specify `dir` explicitly if needed.

gotcha The `alias` property in `ResultDescription` is unpredictable if `replacement` is not specified; it defaults to the generated file path, which may point to a non-existent file if the code is empty or void function. ↓

fix Always provide a valid `code` or return a consistent `replacement` when using alias.

Install

npm install vite-plugin-optimizer

yarn add vite-plugin-optimizer

pnpm add vite-plugin-optimizer

Imports

default

wrong

const optimizer = require('vite-plugin-optimizer'); // CommonJS require is not supported

correct

import optimizer from 'vite-plugin-optimizer'

Package is ESM-only; default export is a function.

OptimizerOptions

wrong

import { OptimizerOptions } from 'vite-plugin-optimizer'; // TypeScript's isolatedModules may cause error; use type import

correct

import type { OptimizerOptions } from 'vite-plugin-optimizer'

Type-only export, use `import type` for type declarations.

Entries

wrong

const { Entries } = require('vite-plugin-optimizer'); // Cannot destructure types from CommonJS

correct

import type { Entries } from 'vite-plugin-optimizer'

TypeScript type; use `import type`.

ResultDescription

import type { ResultDescription } from 'vite-plugin-optimizer'

TypeScript type.

Quickstart

Shows basic usage: replacing a module (vue) with inline code, and aliasing multiple module IDs (fs and node:fs) to a CommonJS module.

import optimizer from 'vite-plugin-optimizer'

export default {
  plugins: [
    optimizer({
      // Replace 'vue' imports with a global variable
      vue: `const vue = window.Vue; export { vue as default }`,
      // Alias 'fs' and 'node:fs' to a CommonJS require
      fs: () => ({
        find: /^(node:)?fs$/,
        code: `const fs = require('fs'); export { fs as default }`
      })
    })
  ]
}