Vite Bundle Optimizer

A Vite plugin for automatic production bundle optimization via intelligent chunk splitting, vendor grouping, shared dependency extraction, and compression.

Features

• Intelligent vendor splitting — automatically groups node_modules into cacheable vendor chunks by ecosystem (react, UI, charts, editor, etc.)
• Shared dependency detection — extracts dependencies used by multiple lazy chunks into shared chunks
• Initial vs lazy awareness — keeps lazy-only vendors out of the initial bundle
• Chunk size limits — merges undersized chunks, enforces max chunk count
• Gzip & Brotli compression — generates .gz and .br files for JS and CSS assets
• Bundle reports — console, JSON, and HTML reports with before/after comparison
• Analyze-only mode — analyze the build and generate recommendations without modifying chunk topology or output files
• Three strategies — conservative, balanced (default), and aggressive
• Framework-agnostic — works with React, Vue, Svelte, Solid, and vanilla

Installation

npm install -D vite-plugin-bundle-optimizer
yarn add -D vite-plugin-bundle-optimizer
pnpm add -D vite-plugin-bundle-optimizer

Quick Start

import { defineConfig } from 'vite';
import bundleOptimizer from 'vite-plugin-bundle-optimizer';

export default defineConfig({
  plugins: [bundleOptimizer()],
});

That's it. The plugin automatically optimizes your production build.

Analyze-Only Mode

Not sure if the plugin will help? Enable analyzeOnly to get a report with recommendations without modifying your build output:

import { defineConfig } from 'vite';
import bundleOptimizer from 'vite-plugin-bundle-optimizer';

export default defineConfig({
  plugins: [
    bundleOptimizer({
      analyzeOnly: true,
      report: {
        format: ['console', 'json', 'html'],
        output: './bundle-report.json',
        detailed: true,
      },
    }),
  ],
});

In this mode the plugin:

• Analyzes the production build — modules, chunks, dependency graph, sizes
• Generates recommendations — shared dependencies, vendor grouping, lazy loading candidates, chunk size issues, initial bundle size
• Does not modify chunk topology, file names, or file contents
• Does not create .gz or .br compression files
• Produces reports in console, JSON, and HTML formats

Each recommendation includes:

Field	Description
id	Stable recommendation type identifier
severity	info, warning, or high
title	Short title
description	What was detected
reason	Why it may be inefficient
evidence	Measurable data backing the recommendation
suggestion	Proposed change
estimatedImpact	Potential effect (only if reliably calculable)

The HTML report supports automatic light/dark theme switching based on the user's system preference.

Configuration

bundleOptimizer({
  enabled: true,

  // Analyze-only mode: analyze and recommend without modifying the build
  analyzeOnly: false,

  // Optimization strategy: 'conservative' | 'balanced' | 'aggressive'
  strategy: 'balanced',

  // Chunk size limits
  minChunkSize: 30_000,   // 30 KB — chunks smaller than this are merged
  maxChunkSize: 500_000,  // 500 KB — target maximum chunk size
  maxChunks: 30,          // Maximum number of chunks

  // Compression
  compression: {
    gzip: true,
    brotli: true,
    gzipLevel: 9,       // 1-9, higher = smaller output
    brotliQuality: 11,  // 0-11, higher = smaller output
  },

  // Reporting
  report: true,           // or { format: 'json', output: './bundle-report.json' }

  // Network assumptions for chunk count tuning
  network: {
    protocol: 'auto',     // 'http1' | 'http2' | 'http3' | 'auto'
  },
});

Explicit Groups

Define custom vendor groups:

bundleOptimizer({
  groups: {
    editor: ['monaco-editor', '@monaco-editor/*'],
    charts: ['chart.js', 'recharts'],
  },
});

This creates editor.[hash].js and charts.[hash].js chunks.

Exclude

Exclude packages from optimization (left to Rollup's default behavior):

bundleOptimizer({
  exclude: ['react', 'react-dom'],
});
// or with regex
exclude: [/@internal/],

Preserve

Prevent specific packages from being redistributed:

bundleOptimizer({
  preserve: ['monaco-editor'],
});

Reports

Console Report (default)

Vite Bundle Optimizer

Before
────────────────────────────────────────────────────────
  Initial JS       2.13 MB
  Initial gzip     616 KB
  Initial chunks   1

After
────────────────────────────────────────────────────────
  Initial JS       540 KB
  Initial gzip     168 KB
  Initial chunks   8

Saved
────────────────────────────────────────────────────────
  Initial JS       -75%
  Initial gzip     -73%

JSON Report

bundleOptimizer({
  report: {
    format: 'json',
    output: './bundle-report.json',
  },
});

HTML Report

bundleOptimizer({
  report: {
    format: 'html',
    output: './bundle-report.html',
  },
});

Multiple Formats

bundleOptimizer({
  report: {
    format: ['console', 'json', 'html'],
    output: './bundle-report.json',
    detailed: true,
  },
});

Performance Budgets

bundleOptimizer({
  failOnError: true,
  budget: {
    initialGzip: 200_000,  // 200 KB max initial gzip
    totalGzip: 1_000_000, // 1 MB max total gzip
  },
});

Strategies

Strategy	minChunkSize	maxChunkSize	maxChunks	Use case
conservative	50 KB	1 MB	15	Legacy apps, minimal changes
balanced (default)	30 KB	500 KB	30	Most applications
aggressive	20 KB	300 KB	50	Maximum initial size reduction

How It Works

The optimization pipeline runs in the following stages:

1. Build handoff — Vite delegates bundling to Rollup, which produces a dependency graph of all modules in the project.
2. Module analysis — The plugin inspects that graph to understand which modules are shared across entry points and which come from third‑party packages.
3. Chunk optimization — Based on the analysis, modules are split into two kinds of dedicated chunks:
   • Shared chunks — code used by multiple entry points, extracted so it isn't duplicated.
   • Vendor chunks — third‑party dependencies, grouped according to the configured vendor groups.
4. Final JS chunks — Shared and vendor chunks are combined with the remaining entry chunks into the final set of JS chunks emitted to dist/assets.
5. Compression — JS and CSS assets are compressed with gzip and brotli, producing .gz and .br files alongside the originals.
6. Compression reporting — Each final chunk is measured with both gzip and brotli to report the actual transfer sizes.

The plugin works at the chunk topology level only — it does not modify, remove, or rewrite application code. Tree shaking remains Rollup's responsibility.

Requirements

• Vite 5+ (supports Vite 5.x, 6.x, 7.x, and 8.x with Rolldown)
• Node.js 20+

License

MIT