vite-bundle-optimization

name	vite-bundle-optimization
description	Teaches Vite-specific bundle optimization patterns. Use when configuring Vite builds, code splitting, managing dependencies, or troubleshooting slow Vite builds.
paths	["**/*.js","**/*.ts"]
license	MIT
metadata	{"author":"patterns.dev","version":"1.1"}
related_skills	["module-pattern","singleton-pattern"]

Vite Bundle Optimization

Table of Contents

• When to Use
• Instructions
• Details
• Source

Production-ready patterns for optimizing bundle size and build performance in Vite + React applications. These patterns leverage Vite's architecture (native ESM in dev, Rollup in production) to deliver smaller, faster bundles.

When to Use

Reference these patterns when:

• Setting up a new Vite + React project for production
• Analyzing bundle size with npx vite-bundle-visualizer
• Build times are slow or bundles are unexpectedly large
• Migrating from webpack/CRA to Vite
• Optimizing Core Web Vitals (LCP, FID/INP, CLS)

Instructions

• Apply these patterns during project setup, build configuration, and bundle size reviews. When you see large bundles or slow builds, diagnose with npx vite-bundle-visualizer and apply the relevant pattern.

Details

Overview

Vite uses esbuild for dependency pre-bundling and development transforms, and Rollup for production builds. Understanding this dual architecture is key to optimizing effectively. The patterns below are ordered by impact.

---

1. Avoid Barrel File Imports

Impact: CRITICAL — Can add 200-800ms to startup and 2-4s to dev server boot.

Barrel files (index.ts that re-export from many modules) force bundlers to load the entire module graph even when you only use one export. This is the #1 bundle size issue in React apps.

Avoid — imports entire library through barrel:

import { Button, TextField } from '@/components'
// Loads ALL components in the barrel, even unused ones

import { Check, X, Menu } from 'lucide-react'
// Loads all 1,500+ icons (~2.8s in dev)

Prefer — direct imports:

import { Button } from '@/components/Button'
import { TextField } from '@/components/TextField'

import Check from 'lucide-react/dist/esm/icons/check'
import X from 'lucide-react/dist/esm/icons/x'
import Menu from 'lucide-react/dist/esm/icons/menu'

Auto-fix with vite-plugin-barrel:

// vite.config.ts
import barrel from 'vite-plugin-barrel'

export default defineConfig({
  plugins: [
    react(),
    barrel({
      packages: ['lucide-react', '@mui/material', '@mui/icons-material'],
    }),
  ],
})

This transforms barrel imports into direct imports at build time, giving you ergonomic syntax with direct-import performance.

Commonly affected libraries: lucide-react, @mui/material, @mui/icons-material, @tabler/icons-react, react-icons, @radix-ui/react-*, lodash, date-fns, rxjs.

---

2. Configure Manual Chunk Splitting

Impact: HIGH — Better caching, parallel loading, smaller initial bundle.

Vite's default chunking puts all vendor code into one file. Split it so that frequently-changing app code doesn't invalidate the vendor cache.

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          // Core React — rarely changes
          'vendor-react': ['react', 'react-dom'],
          // Router — changes infrequently
          'vendor-router': ['react-router-dom'],
          // Data layer — changes occasionally
          'vendor-query': ['@tanstack/react-query'],
          // UI framework — changes with design updates
          'vendor-ui': ['@radix-ui/react-dialog', '@radix-ui/react-dropdown-menu'],
        },
      },
    },
  },
})

For more dynamic splitting based on module paths:

manualChunks(id) {
  if (id.includes('node_modules')) {
    if (id.includes('react-dom')) return 'vendor-react'
    if (id.includes('react-router')) return 'vendor-router'
    if (id.includes('@tanstack')) return 'vendor-query'
    return 'vendor' // everything else
  }
},

---

3. Dynamic Imports for Route-Level Code Splitting

Impact: HIGH — Load only the code needed for the current page.

Use React.lazy() with dynamic imports to split each route into its own chunk.

import { lazy, Suspense } from 'react'
import { BrowserRouter, Routes, Route } from 'react-router-dom'

const Home = lazy(() => import('./pages/Home'))
const Dashboard = lazy(() => import('./pages/Dashboard'))
const Settings = lazy(() => import('./pages/Settings'))

function App() {
  return (
    <BrowserRouter>
      <Suspense fallback={<PageSkeleton />}>
        <Routes>
          <Route path="/" element={<Home />} />
          <Route path="/dashboard" element={<Dashboard />} />
          <Route path="/settings" element={<Settings />} />
        </Routes>
      </Suspense>
    </BrowserRouter>
  )
}

Vite automatically creates separate chunks for each lazy import. Name them for easier debugging:

const Dashboard = lazy(() =>
  import(/* webpackChunkName: "dashboard" */ './pages/Dashboard')
)

---

4. Lazy-Load Heavy Components Below the Fold

Impact: HIGH — Reduces initial bundle for faster LCP.

Components that aren't visible on initial load (modals, charts, editors, maps) should be lazy-loaded.

import { lazy, Suspense, useState } from 'react'

const RichTextEditor = lazy(() => import('./components/RichTextEditor'))
const ChartPanel = lazy(() => import('./components/ChartPanel'))

function ArticlePage() {
  const [editing, setEditing] = useState(false)

  return (
    <article>
      <h1>Article Title</h1>
      <p>Content visible immediately...</p>

      {editing && (
        <Suspense fallback={<EditorSkeleton />}>
          <RichTextEditor />
        </Suspense>
      )}

      <Suspense fallback={<ChartSkeleton />}>
        <ChartPanel />
      </Suspense>
    </article>
  )
}

---

5. Defer Third-Party Scripts

Impact: HIGH — Analytics, tracking, and widgets shouldn't block rendering.

Load non-critical third-party scripts after the page is interactive.

Avoid — blocks initial render:

// main.tsx
import * as Sentry from '@sentry/react'
import posthog from 'posthog-js'

Sentry.init({ dsn: '...' })
posthog.init('...')

Prefer — load after hydration/mount:

// main.tsx — defer to idle time
function initThirdParty() {
  import('@sentry/react').then(Sentry => {
    Sentry.init({ dsn: import.meta.env.VITE_SENTRY_DSN })
  })
  import('posthog-js').then(({ default: posthog }) => {
    posthog.init(import.meta.env.VITE_POSTHOG_KEY)
  })
}

if ('requestIdleCallback' in window) {
  requestIdleCallback(initThirdParty)
} else {
  setTimeout(initThirdParty, 2000)
}

For external script tags, use defer or dynamically inject them:

function loadScript(src: string) {
  const script = document.createElement('script')
  script.src = src
  script.async = true
  document.body.appendChild(script)
}

---

6. Preload Critical Assets on User Intent

Impact: MEDIUM — Eliminates perceived latency on navigation.

Start loading a route's code when the user signals intent (hover, focus) rather than waiting for the click.

function NavLink({ to, children }: { to: string; children: React.ReactNode }) {
  const preload = () => {
    // Vite creates a module preload for dynamic imports
    switch (to) {
      case '/dashboard':
        import('./pages/Dashboard')
        break
      case '/settings':
        import('./pages/Settings')
        break
    }
  }

  return (
    <Link to={to} onMouseEnter={preload} onFocus={preload}>
      {children}
    </Link>
  )
}

For <link rel="modulepreload"> in the HTML head:

<!-- Preload critical route chunks -->
<link rel="modulepreload" href="/assets/Home-abc123.js" />

Vite automatically adds <link rel="modulepreload"> for entry chunks. Add manual preloads for routes you know users will visit next.

---

7. Configure Dependency Pre-Bundling

Impact: MEDIUM — Faster dev server startup and page loads.

Vite pre-bundles node_modules dependencies using esbuild. Configure it to handle edge cases.

// vite.config.ts
export default defineConfig({
  optimizeDeps: {
    // Force pre-bundle these (useful for CJS deps or deep imports)
    include: [
      'react',
      'react-dom',
      'react-router-dom',
      '@tanstack/react-query',
      'date-fns/format',
      'date-fns/parseISO',
    ],
    // Skip pre-bundling for these (already ESM, or causes issues)
    exclude: ['@vite-pwa/assets-generator'],
  },
})

If you see slow page loads in dev with many small requests, it's usually because a dependency isn't pre-bundled. Add it to include.

---

8. Enable Compression

Impact: MEDIUM — 60-80% smaller transfer sizes.

Vite doesn't compress by default. Add the compression plugin for production.

// vite.config.ts
import viteCompression from 'vite-plugin-compression'

export default defineConfig({
  plugins: [
    react(),
    viteCompression({ algorithm: 'gzip' }),
    viteCompression({ algorithm: 'brotliCompress' }),
  ],
})

This generates .gz and .br files alongside your assets. Configure your server (Nginx, Cloudflare, Vercel) to serve them.

---

9. Analyze Your Bundle Regularly

Impact: INFORMATIONAL — Catch size regressions before they ship.

Run the bundle visualizer after every significant dependency change.

npx vite-bundle-visualizer

Or add it to your build script:

{
  "scripts": {
    "build": "vite build",
    "analyze": "vite build && npx vite-bundle-visualizer"
  }
}

What to look for:

• Any single chunk > 200KB gzipped — consider splitting
• Duplicate libraries loaded in multiple chunks
• Full library loaded when only a few functions are used
• node_modules code that could be dynamically imported

---

10. Use import.meta.env for Dead Code Elimination

Impact: LOW-MEDIUM — Removes unused code paths in production.

Vite replaces import.meta.env.* at build time, allowing Rollup to tree-shake dead branches.

// This code is completely removed in production
if (import.meta.env.DEV) {
  console.log('Debug info:', data)
  window.__DEBUG_DATA__ = data
}

// Feature flags eliminated at build time
if (import.meta.env.VITE_FEATURE_NEW_DASHBOARD === 'true') {
  // Only included when flag is set
  initNewDashboard()
}

Define custom env variables in .env files:

# .env.production
VITE_FEATURE_NEW_DASHBOARD=true
VITE_API_URL=https://api.example.com

---

11. Optimize Images and Static Assets

Impact: MEDIUM — Images are typically the largest assets.

Configure asset handling in Vite:

// vite.config.ts
export default defineConfig({
  build: {
    assetsInlineLimit: 4096, // Inline assets < 4KB as base64
    rollupOptions: {
      output: {
        assetFileNames: (assetInfo) => {
          // Organize assets by type
          if (/\.(png|jpe?g|gif|svg|webp|avif)$/.test(assetInfo.name ?? '')) {
            return 'images/[name]-[hash][extname]'
          }
          if (/\.(woff2?|ttf|eot)$/.test(assetInfo.name ?? '')) {
            return 'fonts/[name]-[hash][extname]'
          }
          return 'assets/[name]-[hash][extname]'
        },
      },
    },
  },
})

Use vite-plugin-image-optimizer for automatic image compression:

import { ViteImageOptimizer } from 'vite-plugin-image-optimizer'

export default defineConfig({
  plugins: [
    react(),
    ViteImageOptimizer({
      png: { quality: 80 },
      jpeg: { quality: 80 },
      webp: { quality: 80 },
    }),
  ],
})

---

12. Configure Dev Server Proxy for API Development

Impact: MEDIUM — Eliminates CORS issues and simplifies local development.

Vite SPAs typically talk to a separate backend API. Configure server.proxy to forward API requests during development, avoiding CORS and matching production URL patterns.

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:3001',
        changeOrigin: true,
      },
      '/auth': {
        target: 'http://localhost:3001',
        changeOrigin: true,
      },
      // WebSocket support for real-time features
      '/ws': {
        target: 'ws://localhost:3001',
        ws: true,
      },
    },
  },
})

In your app code, use relative paths (fetch('/api/users')) — they hit Vite's dev server which proxies to your backend. In production, configure your reverse proxy (Nginx, Caddy) to do the same routing.

---

13. Add PWA Support with vite-plugin-pwa

Impact: MEDIUM — Offline capability, installability, and cached assets for Vite SPAs.

For SPAs that need offline support or installability, vite-plugin-pwa handles service worker generation, precaching, and manifest creation.

// vite.config.ts
import { VitePWA } from 'vite-plugin-pwa'

export default defineConfig({
  plugins: [
    react(),
    VitePWA({
      registerType: 'autoUpdate',
      includeAssets: ['favicon.svg', 'robots.txt'],
      manifest: {
        name: 'My App',
        short_name: 'App',
        theme_color: '#ffffff',
        icons: [
          { src: '/icon-192.png', sizes: '192x192', type: 'image/png' },
          { src: '/icon-512.png', sizes: '512x512', type: 'image/png' },
        ],
      },
      workbox: {
        globPatterns: ['**/*.{js,css,html,ico,png,svg,woff2}'],
        runtimeCaching: [
          {
            urlPattern: /^https:\/\/api\./,
            handler: 'NetworkFirst',
            options: { cacheName: 'api-cache', expiration: { maxEntries: 50 } },
          },
        ],
      },
    }),
  ],
})

Use registerType: 'autoUpdate' for apps that should silently update. Use registerType: 'prompt' to show users an update notification.

---

14. Choose a CSS Strategy

Impact: MEDIUM — Vite supports multiple CSS approaches with zero config.

Vite handles CSS Modules, PostCSS, and preprocessors out of the box. Choose based on your needs:

CSS Modules — scoped styles, no runtime cost, built into Vite:

// Button.module.css → automatically scoped
import styles from './Button.module.css'

function Button({ children }: { children: React.ReactNode }) {
  return <button className={styles.primary}>{children}</button>
}

Tailwind CSS — utility-first, works with Vite's PostCSS support:

// vite.config.ts — no plugin needed, Tailwind uses PostCSS
// Just install tailwindcss and add postcss.config.js

// postcss.config.js
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

CSS-in-JS considerations: Libraries like styled-components and Emotion add runtime overhead. For Vite SPAs prioritizing performance, prefer CSS Modules or Tailwind. If you need CSS-in-JS, consider zero-runtime options like Vanilla Extract or Panda CSS.

---

15. Set Up the React Compiler as a Vite Plugin

Impact: HIGH — Automatic memoization eliminates manual useMemo, useCallback, and React.memo.

The React Compiler analyzes your components and auto-inserts memoization. In a Vite project, add it as a Babel plugin:

npm install -D babel-plugin-react-compiler

// vite.config.ts
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [
    react({
      babel: {
        plugins: ['babel-plugin-react-compiler'],
      },
    }),
  ],
})

Once enabled, you can gradually remove manual useMemo, useCallback, and React.memo calls — the compiler handles them automatically. Verify behavior is preserved by running your test suite after enabling.

The compiler requires React 19. It's opt-in and can be enabled per-file with a 'use memo' directive if you prefer incremental adoption.

---

Source

Patterns from patterns.dev — Vite-specific optimization guidance for the broader React web engineering community.