React + Vite Best Practices

Comprehensive performance optimization guide for React applications built with Vite. Contains 23 rules across 6 categories for build optimization, code splitting, development performance, asset handling, environment configuration, and bundle analysis.

Metadata

• Version: 2.0.0
• Framework: React + Vite
• Rule Count: 23 rules across 6 categories
• License: MIT

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 and HMR
• Handling images, fonts, SVGs, and static assets
• Managing environment variables across environments
• Analyzing bundle size and dependencies

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Build Optimization	CRITICAL	build-
2	Code Splitting	CRITICAL	split-
3	Development	HIGH	dev-
4	Asset Handling	HIGH	asset-
5	Environment Config	MEDIUM	env-
6	Bundle Analysis	MEDIUM	bundle-

Quick Reference

1. Build Optimization (CRITICAL)

• build-manual-chunks - Configure manual chunks for vendor separation
• build-minification - Minification with OXC (default) or Terser
• build-target-modern - Target modern browsers (baseline-widely-available)
• build-sourcemaps - Configure sourcemaps per environment
• build-tree-shaking - Ensure proper tree shaking with ESM
• build-compression - Gzip and Brotli compression
• build-asset-hashing - Content-based hashing for cache busting

2. Code Splitting (CRITICAL)

• split-route-lazy - Route-based splitting with React.lazy()
• split-suspense-boundaries - Strategic Suspense boundary placement
• split-dynamic-imports - Dynamic import() for heavy components
• split-component-lazy - Lazy load non-critical components
• split-prefetch-hints - Prefetch chunks on hover/idle/viewport

3. Development (HIGH)

• dev-dependency-prebundling - Configure optimizeDeps for faster starts
• dev-fast-refresh - React Fast Refresh patterns
• dev-hmr-config - HMR server configuration

4. Asset Handling (HIGH)

• asset-image-optimization - Image optimization and lazy loading
• asset-svg-components - SVGs as React components with SVGR
• asset-fonts - Web font loading strategy
• asset-public-dir - Public directory vs JavaScript imports

5. Environment Config (MEDIUM)

• env-vite-prefix - VITE_ prefix for client variables
• env-modes - Mode-specific environment files
• env-sensitive-data - Never expose secrets in client code

6. Bundle Analysis (MEDIUM)

• bundle-visualizer - Analyze bundles with rollup-plugin-visualizer

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: 'baseline-widely-available',
    sourcemap: false,
    chunkSizeWarningLimit: 500,
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
        },
      },
    },
  },

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

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

Route-Based Code Splitting

import { lazy, Suspense } from 'react'

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

function App() {
  return (
    <Suspense fallback={<LoadingSpinner />}>
      {/* Routes here */}
    </Suspense>
  )
}

Environment Variables

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

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

interface ImportMeta {
  readonly env: ImportMetaEnv
}

How to Use

Read individual rule files for detailed explanations and code examples:

rules/build-manual-chunks.md
rules/split-route-lazy.md
rules/env-vite-prefix.md

References

• Vite Documentation
• React Documentation
• Rollup Documentation

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md