react-vite-best-practices

Original source / Raw SKILL.md

---
name: react-vite-best-practices
description: React and Vite performance optimization guidelines. Use when writing, reviewing, or optimizing React components built with Vite. Triggers on tasks involving Vite configuration, build optimization, code splitting, lazy loading, HMR, bundle size, or React performance.
license: MIT
metadata:
  author: agent-skills
  version: "1.0.0"
---

# 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

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Build Optimization | CRITICAL | `build-` |
| 2 | Code Splitting | CRITICAL | `split-` |
| 3 | Development Performance | HIGH | `dev-` |
| 4 | Asset Handling | HIGH | `asset-` |
| 5 | Environment Config | MEDIUM | `env-` |
| 6 | HMR Optimization | MEDIUM | `hmr-` |
| 7 | Bundle Analysis | LOW-MEDIUM | `bundle-` |
| 8 | Advanced Patterns | LOW | `advanced-` |

## 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

```typescript
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

```typescript
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

```typescript
// 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
}
```

```typescript
// 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


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### rules/build-manual-chunks.md

```markdown
---
title: Configure Manual Chunks for Vendor Separation
impact: CRITICAL
impactDescription: Optimal caching and parallel loading
tags: build, chunks, vendor, optimization, rollup
---

## Configure Manual Chunks for Vendor Separation

**Impact: CRITICAL (Optimal caching and parallel loading)**

Without manual chunks, Vite bundles all vendor dependencies into a single chunk or mixes them with application code. This leads to:
- Large initial bundle downloads
- Poor cache efficiency (vendor code changes with app code)
- Slower subsequent page loads

## Incorrect

```typescript
// vite.config.ts
export default defineConfig({
  plugins: [react()],
  build: {
    // No manual chunks configured
    // All code bundled together
  },
})
```

**Problem:** React, React DOM, and other vendors are bundled with your application code. When you update your app, users must re-download everything.

## Correct

```typescript
// 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 occasionally
          'vendor-router': ['react-router-dom'],

          // UI library - if using one
          // 'vendor-ui': ['@headlessui/react', '@heroicons/react'],

          // State management
          // 'vendor-state': ['zustand', '@tanstack/react-query'],
        },
      },
    },
  },
})
```

## Advanced: Dynamic Manual Chunks

```typescript
// vite.config.ts
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks(id) {
          // Node modules go to vendor chunk
          if (id.includes('node_modules')) {
            // Split large libraries into separate chunks
            if (id.includes('react-dom')) {
              return 'vendor-react-dom'
            }
            if (id.includes('react')) {
              return 'vendor-react'
            }
            if (id.includes('@tanstack')) {
              return 'vendor-tanstack'
            }
            // Other node_modules
            return 'vendor'
          }
        },
      },
    },
  },
})
```

## Benefits

- **Better caching:** Vendor chunks cached separately from app code
- **Parallel loading:** Browser can download multiple chunks simultaneously
- **Smaller updates:** App changes don't invalidate vendor cache

```

### rules/_sections.md

```markdown
# Sections

This file defines all sections, their ordering, impact levels, and descriptions.
The section ID (in parentheses) is the filename prefix used to group rules.

---

## 1. Build Optimization (build)

**Impact:** CRITICAL
**Description:** Optimizing Vite build configuration and output has the highest impact on production bundle size, load time, and caching efficiency. These rules ensure minimal bundle size and optimal delivery.

## 2. Code Splitting (split)

**Impact:** CRITICAL
**Description:** Strategic code splitting reduces initial bundle size by 50-80%, dramatically improving Time to Interactive and First Contentful Paint. Load only what's needed, when it's needed.

## 3. Development Performance (dev)

**Impact:** HIGH
**Description:** Fast development iteration with instant feedback loops. Optimizing Vite's dev server, dependency pre-bundling, and HMR reduces build times and improves developer productivity.

## 4. Asset Handling (asset)

**Impact:** HIGH
**Description:** Proper asset optimization (images, SVGs, fonts) reduces page weight by 40-70% and improves Core Web Vitals. Critical for performance on slower networks.

## 5. Environment Configuration (env)

**Impact:** MEDIUM
**Description:** Proper environment variable handling ensures security (no leaked secrets) and correct configuration across development, staging, and production environments.

## 6. HMR Optimization (hmr)

**Impact:** MEDIUM
**Description:** React Fast Refresh and HMR optimization preserve component state during development, enabling instant visual feedback without full page reloads.

## 7. Bundle Analysis (bundle)

**Impact:** LOW-MEDIUM
**Description:** Tools and techniques for analyzing bundle composition, identifying bloat, and ensuring proper tree shaking. Essential for maintaining long-term bundle health.

## 8. Advanced Patterns (advanced)

**Impact:** LOW
**Description:** Specialized patterns for SSR, library mode, multi-page apps, Web Workers, and WebAssembly. Apply only when these specific use cases are required.

```