React + Vite Best Practices

Comprehensive performance optimization guide for React applications built with Vite. Contains 40+ rules across 8 categories, prioritized by impact to guide code generation and refactoring.

When to Apply

Reference these guidelines when:

• Configuring Vite for React projects
• Implementing code splitting and lazy loading
• Optimizing build output and bundle size
• Setting up development environment
• Reviewing code for performance issues

Rule Categories by Priority

Quick Reference

1. Build Optimization (CRITICAL)

• build-manual-chunks – Configure manual chunks for vendor separation
• build-minify-terser – Use Terser for production minification
• build-target-modern – Target modern browsers for smaller bundles
• build-sourcemap-production – Configure sourcemaps appropriately
• build-output-structure – Organize output directory structure
• build-chunk-size-limit – Set appropriate chunk size warnings

2. Code Splitting (CRITICAL)

• split-route-lazy – Use React.lazy() for route-based splitting
• split-suspense-boundaries – Wrap lazy components with Suspense
• split-dynamic-imports – Use dynamic imports for heavy components
• split-preload-critical – Preload critical chunks on interaction
• split-named-chunks – Use named chunks for better caching
• split-vendor-separation – Separate vendor from application code

3. Development Performance (HIGH)

• dev-dependency-prebundling – Configure dependency pre-bundling
• dev-exclude-large-deps – Exclude large deps from optimization
• dev-warmup-frequent – Warmup frequently used modules
• dev-server-config – Optimize dev server configuration
• dev-hmr-overlay – Configure HMR error overlay

4. Asset Handling (HIGH)

• asset-inline-limit – Set appropriate asset inline limit
• asset-public-dir – Configure public directory correctly
• asset-import-syntax – Use correct asset import syntax
• asset-svg-components – Handle SVGs as React components
• asset-image-optimization – Optimize image loading
• asset-font-loading – Optimize font loading strategy

5. Environment Configuration (MEDIUM)

• env-vite-prefix – Use VITE_ prefix for client variables
• env-type-definitions – Type environment variables
• env-mode-specific – Use mode-specific env files
• env-sensitive-data – Never expose sensitive data
• env-build-time – Understand build-time replacement

6. HMR Optimization (MEDIUM)

• hmr-fast-refresh – Ensure Fast Refresh works correctly
• hmr-preserve-state – Preserve component state during HMR
• hmr-boundary-setup – Set up proper HMR boundaries
• hmr-custom-handlers – Implement custom HMR handlers

7. Bundle Analysis (LOW-MEDIUM)

• bundle-visualizer – Use rollup-plugin-visualizer
• bundle-analyze-deps – Analyze dependency sizes
• bundle-tree-shaking – Ensure proper tree shaking
• bundle-dead-code – Eliminate dead code
• bundle-css-splitting – Configure CSS code splitting

8. Advanced Patterns (LOW)

• advanced-ssr-config – Configure for SSR if needed
• advanced-library-mode – Build as library
• advanced-multi-page – Multi-page application setup
• advanced-worker-threads – Web Worker integration
• advanced-wasm – WebAssembly integration

Essential Configurations

Recommended vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],

  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },

  build: {
    target: 'esnext',
    minify: 'terser',
    sourcemap: false,
    chunkSizeWarningLimit: 500,
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
          router: ['react-router-dom'],
        },
      },
    },
    terserOptions: {
      compress: {
        drop_console: true,
        drop_debugger: true,
      },
    },
  },

  optimizeDeps: {
    include: ['react', 'react-dom'],
  },

  server: {
    port: 3000,
    open: true,
    hmr: {
      overlay: true,
    },
  },
})

Route-Based Code Splitting

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

// Lazy load route components
const Home = lazy(() => import('./pages/Home'))
const Dashboard = lazy(() => import('./pages/Dashboard'))
const Settings = lazy(() => import('./pages/Settings'))

// Named chunks for better debugging
const Profile = lazy(() =>
  import(/* webpackChunkName: "profile" */ './pages/Profile')
)

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

Environment Variables

// src/vite-env.d.ts
/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_API_URL: string
  readonly VITE_APP_TITLE: string
  readonly VITE_ENABLE_ANALYTICS: string
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

// Usage
const apiUrl = import.meta.env.VITE_API_URL
const isDev = import.meta.env.DEV
const isProd = import.meta.env.PROD

How to Use

Read individual rule files for detailed explanations and code examples:

rules/build-manual-chunks.md
rules/split-route-lazy.md
rules/_sections.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Additional context and references