{"id":22767,"library":"vite-plugin-optimizer","title":"vite-plugin-optimizer","description":"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).","status":"active","version":"1.4.3","language":"javascript","source_language":"en","source_url":"https://github.com/vite-plugin/vite-plugin-optimizer","tags":["javascript","vite","build","plugin","external","optimizer","Pre-Bundling","typescript"],"install":[{"cmd":"npm install vite-plugin-optimizer","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-optimizer","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-optimizer","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Package is ESM-only; default export is a function.","wrong":"const optimizer = require('vite-plugin-optimizer'); // CommonJS require is not supported","symbol":"default","correct":"import optimizer from 'vite-plugin-optimizer'"},{"note":"Type-only export, use `import type` for type declarations.","wrong":"import { OptimizerOptions } from 'vite-plugin-optimizer'; // TypeScript's isolatedModules may cause error; use type import","symbol":"OptimizerOptions","correct":"import type { OptimizerOptions } from 'vite-plugin-optimizer'"},{"note":"TypeScript type; use `import type`.","wrong":"const { Entries } = require('vite-plugin-optimizer'); // Cannot destructure types from CommonJS","symbol":"Entries","correct":"import type { Entries } from 'vite-plugin-optimizer'"},{"note":"TypeScript type.","wrong":"","symbol":"ResultDescription","correct":"import type { ResultDescription } from 'vite-plugin-optimizer'"}],"quickstart":{"code":"import optimizer from 'vite-plugin-optimizer'\n\nexport default {\n  plugins: [\n    optimizer({\n      // Replace 'vue' imports with a global variable\n      vue: `const vue = window.Vue; export { vue as default }`,\n      // Alias 'fs' and 'node:fs' to a CommonJS require\n      fs: () => ({\n        find: /^(node:)?fs$/,\n        code: `const fs = require('fs'); export { fs as default }`\n      })\n    })\n  ]\n}","lang":"typescript","description":"Shows basic usage: replacing a module (vue) with inline code, and aliasing multiple module IDs (fs and node:fs) to a CommonJS module."},"warnings":[{"fix":"Return an object with `alias` property from the function, or return a string for code.","message":"Using a function with no return value (void) will skip alias registration; you must explicitly return an alias object.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Add the module id to `optimizeDeps.include` if you want Vite to pre-bundle it anyway.","message":"Modules defined in optimizer entries are automatically added to `optimizeDeps.exclude`. To pre-bundle them instead, add them to `optimizeDeps.include`.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"No action needed unless you relied on the old default path; specify `dir` explicitly if needed.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always provide a valid `code` or return a consistent `replacement` when using alias.","message":"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.","severity":"gotcha","affected_versions":">=1.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Change to ES module import: `import optimizer from 'vite-plugin-optimizer'`.","cause":"Using CommonJS `require` to import the ESM-only package.","error":"require is not defined in ES module scope (vite-plugin-optimizer default export is not a function)"},{"fix":"Run `npm i vite-plugin-optimizer -D` and ensure `tsconfig.json` includes `moduleResolution: 'node'` and `esModuleInterop: true`.","cause":"Missing installation or TypeScript configuration.","error":"Cannot find module 'vite-plugin-optimizer' or its corresponding type declarations."},{"fix":"Ensure `ResultDescription.alias` includes both `find` (string/RegExp) and `replacement` (string).","cause":"The `alias` property in `ResultDescription` must have `find` and `replacement`; missing one.","error":"Plugin returned an object with 'alias' property that is not in resolve.alias format"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}