React 19 + Vite Best Practices

React 19 component patterns and Vite performance optimization guide. Contains 40+ rules across 9 categories, prioritized by impact to guide code generation and refactoring.

When to Apply

Reference these guidelines when:

• Writing new React components or hooks

• 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 React 19 Patterns CRITICAL react-

2 Build Optimization CRITICAL build-

3 Code Splitting CRITICAL split-

4 Development Performance HIGH dev-

5 Asset Handling HIGH asset-

6 Environment Config MEDIUM env-

7 HMR Optimization MEDIUM hmr-

8 Bundle Analysis LOW-MEDIUM bundle-

9 Advanced Patterns LOW advanced-

Quick Reference

1. React 19 Patterns (CRITICAL)

• react-named-imports

• Always use named imports from "react"

• react-ref-as-prop

• Use ref as a regular prop (no forwardRef)

• react-no-default-import

• Never use import React from "react" or import * as React

Named Imports (REQUIRED)

// ✅ ALWAYS: Named imports import { useState, useEffect, useRef } from "react";

// ❌ NEVER: Default or namespace imports import React from "react"; import * as React from "react";

ref as Prop (No forwardRef)

In new custom components, accept ref as a regular prop. Do not use forwardRef .

// ✅ React 19: ref is just a prop function Input({ ref, ...props }: { ref?: React.Ref<HTMLInputElement> } & InputProps) { return <input ref={ref} {...props} />; }

// ❌ Old way (unnecessary in React 19) const Input = forwardRef<HTMLInputElement, InputProps>((props, ref) => ( <input ref={ref} {...props} /> ));

Note: Do NOT refactor existing forwardRef in src/components/ui/ (shadcn). Only apply to new custom components.

2. 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

3. 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

4. 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

5. 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

6. 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

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

8. 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

9. 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