[ PROMPT_NODE_27901 ]

React Performance Guidelines

[ SKILL_DOCUMENTATION ]

# React Best Practices - Complete Document **Version 0.1.0** Vercel Engineering January 2026 > **Note:** > This document is mainly for agents and LLMs to follow when maintaining, generating, or refactoring React and Next.js codebases at Vercel. --- ## Abstract Comprehensive performance optimization guide for React and Next.js applications, designed for AI agents and LLMs. Contains 40+ rules across 8 categories, prioritized by impact from critical (eliminating waterfalls, reducing bundle size) to incremental (advanced patterns). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation. --- ## Table of Contents 1. [Eliminating Waterfalls](#1-eliminating-waterfalls) — **CRITICAL** - 1.1 [Defer Await Until Needed](#11) - 1.2 [Dependency-Based Parallelization](#12) - 1.3 [Prevent Waterfall Chains in API Routes](#13) - 1.4 [Promise.all() for Independent Operations](#14) - 1.5 [Strategic Suspense Boundaries](#15) 2. [Bundle Size Optimization](#2-bundle-size-optimization) — **CRITICAL** - 2.1 [Avoid Barrel File Imports](#21) - 2.2 [Conditional Module Loading](#22) - 2.3 [Defer Non-Critical Third-Party Libraries](#23) - 2.4 [Dynamic Imports for Heavy Components](#24) - 2.5 [Preload Based on User Intent](#25) 3. [Server-Side Performance](#3-server-side-performance) — **HIGH** - 3.1 [Cross-Request LRU Caching](#31) - 3.2 [Minimize Serialization at RSC Boundaries](#32) - 3.3 [Parallel Data Fetching with Component Composition](#33) - 3.4 [Per-Request Deduplication with React.cache()](#34) 4. [Client-Side Data Fetching](#4-client-side-data-fetching) — **MEDIUM-HIGH** - 4.1 [Deduplicate Global Event Listeners](#41) - 4.2 [Use SWR for Automatic Deduplication](#42) 5. [Re-render Optimization](#5-re-render-optimization) — **MEDIUM** - 5.1 [Defer State Reads to Usage Point](#51) - 5.2 [Extract to Memoized Components](#52) - 5.3 [Narrow Effect Dependencies](#53) - 5.4 [Subscribe to Derived State](#54) - 5.5 [Use Lazy State Initialization](#55) - 5.6 [Use Transitions for Non-Urgent Updates](#56) 6. [Rendering Performance](#6-rendering-performance) — **MEDIUM** - 6.1 [Animate SVG Wrapper Instead of SVG Element](#61) - 6.2 [CSS content-visibility for Long Lists](#62) - 6.3 [Hoist Static JSX Elements](#63) - 6.4 [Optimize SVG Precision](#64) - 6.5 [Prevent Hydration Mismatch Without Flickering](#65) - 6.6 [Use Activity Component for Show/Hide](#66) - 6.7 [Use Explicit Conditional Rendering](#67) 7. [JavaScript Performance](#7-javascript-performance) — **LOW-MEDIUM** - 7.1 [Batch DOM CSS Changes](#71) - 7.2 [Build Index Maps for Repeated Lookups](#72) - 7.3 [Cache Property Access in Loops](#73) - 7.4 [Cache Repeated Function Calls](#74) - 7.5 [Cache Storage API Calls](#75) - 7.6 [Combine Multiple Array Iterations](#76) - 7.7 [Early Length Check for Array Comparisons](#77) - 7.8 [Early Return from Functions](#78) - 7.9 [Hoist RegExp Creation](#79) - 7.10 [Use Loop for Min/Max Instead of Sort](#710) - 7.11 [Use Set/Map for O(1) Lookups](#711) - 7.12 [Use toSorted() Instead of sort() for Immutability](#712) 8. [Advanced Patterns](#8-advanced-patterns) — **LOW** - 8.1 [Store Event Handlers in Refs](#81) - 8.2 [useLatest for Stable Callback Refs](#82) --- ## 1. Eliminating Waterfalls **Impact: CRITICAL** Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains. ### 1.1 Defer Await Until Needed Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them. **Incorrect: blocks both branches** ```typescript async function handleRequest(userId: string, skipProcessing: boolean) { const userData = await fetchUserData(userId) if (skipProcessing) { // Returns immediately but still waited for userData return { skipped: true } } // Only this branch uses userData return processUserData(userData) } ``` **Correct: only blocks when needed** ```typescript async function handleRequest(userId: string, skipProcessing: boolean) { if (skipProcessing) { // Returns immediately without waiting return { skipped: true } } // Fetch only when needed const userData = await fetchUserData(userId) return processUserData(userData) } ``` **Another example: early return optimization** ```typescript // Incorrect: always fetches permissions async function updateResource(resourceId: string, userId: string) { const permissions = await fetchPermissions(userId) const resource = await getResource(resourceId) if (!resource) { return { error: 'Not found' } } if (!permissions.canEdit) { return { error: 'Forbidden' } } return await updateResourceData(resource, permissions) } // Correct: fetches only when needed async function updateResource(resourceId: string, userId: string) { const resource = await getResource(resourceId) if (!resource) { return { error: 'Not found' } } const permissions = await fetchPermissions(userId) if (!permissions.canEdit) { return { error: 'Forbidden' } } return await updateResourceData(resource, permissions) } ``` This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive. ### 1.2 Dependency-Based Parallelization For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment. **Incorrect: profile waits for config unnecessarily** ```typescript const [user, config] = await Promise.all([ fetchUser(), fetchConfig() ]) const profile = await fetchProfile(user.id) ``` **Correct: config and profile run in parallel** ```typescript import { all } from 'better-all' const { user, config, profile } = await all({ async user() { return fetchUser() }, async config() { return fetchConfig() }, async profile() { return fetchProfile((await this.$.user).id) } }) ``` Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all) ### 1.3 Prevent Waterfall Chains in API Routes In API routes and Server Actions, start independent operations immediately, even if you don't await them yet. **Incorrect: config waits for auth, data waits for both** ```typescript export async function GET(request: Request) { const session = await auth() const config = await fetchConfig() const data = await fetchData(session.user.id) return Response.json({ data, config }) } ``` **Correct: auth and config start immediately** ```typescript export async function GET(request: Request) { const sessionPromise = auth() const configPromise = fetchConfig() const session = await sessionPromise const [config, data] = await Promise.all([ configPromise, fetchData(session.user.id) ]) return Response.json({ data, config }) } ``` For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization). ### 1.4 Promise.all() for Independent Operations When async operations have no interdependencies, execute them concurrently using `Promise.all()`. **Incorrect: sequential execution, 3 round trips** ```typescript const user = await fetchUser() const posts = await fetchPosts() const comments = await fetchComments() ``` **Correct: parallel execution, 1 round trip** ```typescript const [user, posts, comments] = await Promise.all([ fetchUser(), fetchPosts(), fetchComments() ]) ``` ### 1.5 Strategic Suspense Boundaries Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads. **Incorrect: wrapper blocked by data fetching** ```tsx async function Page() { const data = await fetchData() // Blocks entire page return (

Sidebar

Header

Footer

) } ``` The entire layout waits for data even though only the middle section needs it. **Correct: wrapper shows immediately, data streams in** ```tsx function Page() { return (

Sidebar

Header

Footer

) } async function DataDisplay() { const data = await fetchData() // Only blocks this component return

{data.content}

} ``` Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data. --- ## 2. Bundle Size Optimization **Impact: CRITICAL** Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint. ### 2.1 Avoid Barrel File Imports Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`). Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts. **Incorrect: imports entire library** ```tsx import { Check, X, Menu } from 'lucide-react' // Loads 1,583 modules, takes ~2.8s extra in dev // Runtime cost: 200-800ms on every cold start import { Button, TextField } from '@mui/material' // Loads 2,225 modules, takes ~4.2s extra in dev ``` **Correct: imports only what you need** ```tsx 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' // Loads only 3 modules (~2KB vs ~1MB) import Button from '@mui/material/Button' import TextField from '@mui/material/TextField' // Loads only what you use ``` **Alternative: Next.js 13.5+** ```js // next.config.js - use optimizePackageImports module.exports = { experimental: { optimizePackageImports: ['lucide-react', '@mui/material'] } } // Then you can keep the ergonomic barrel imports: import { Check, X, Menu } from 'lucide-react' // Automatically transformed to direct imports at build time ``` Direct imports provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR. Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`. Reference: [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js) ### 2.2 Conditional Module Loading Load large data or modules only when a feature is activated. **Example: lazy-load animation frames** ```tsx function AnimationPlayer({ enabled }: { enabled: boolean }) { const [frames, setFrames] = useState(null) useEffect(() => { if (enabled && !frames && typeof window !== 'undefined') { import('./animation-frames.js') .then(mod => setFrames(mod.frames)) .catch(() => setEnabled(false)) } }, [enabled, frames]) if (!frames) return return } ``` The `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed. ### 2.3 Defer Non-Critical Third-Party Libraries Analytics, logging, and error tracking don't block user interaction. Load them after hydration. **Incorrect: blocks initial bundle** ```tsx import { Analytics } from '@vercel/analytics/react' export default function RootLayout({ children }) { return ( {children} ) } ``` **Correct: loads after hydration** ```tsx import dynamic from 'next/dynamic' const Analytics = dynamic( () => import('@vercel/analytics/react').then(m => m.Analytics), { ssr: false } ) export default function RootLayout({ children }) { return ( {children} ) } ``` ### 2.4 Dynamic Imports for Heavy Components Use `next/dynamic` to lazy-load large components not needed on initial render. **Incorrect: Monaco bundles with main chunk ~300KB** ```tsx import { MonacoEditor } from './monaco-editor' function CodePanel({ code }: { code: string }) { return } ``` **Correct: Monaco loads on demand** ```tsx import dynamic from 'next/dynamic' const MonacoEditor = dynamic( () => import('./monaco-editor').then(m => m.MonacoEditor), { ssr: false } ) function CodePanel({ code }: { code: string }) { return } ``` ### 2.5 Preload Based on User Intent Preload heavy bundles before they're needed to reduce perceived latency. **Example: preload on hover/focus** ```tsx function EditorButton({ onClick }: { onClick: () => void }) { const preload = () => { if (typeof window !== 'undefined') { void import('./monaco-editor') } } return ( ) } ``` **Example: preload when feature flag is enabled** ```tsx function FlagsProvider({ children, flags }: Props) { useEffect(() => { if (flags.editorEnabled && typeof window !== 'undefined') { void import('./monaco-editor').then(mod => mod.init()) } }, [flags.editorEnabled]) return {children} } ``` The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed. --- ## 3. Server-Side Performance **Impact: HIGH** Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times. ### 3.1 Cross-Request LRU Caching `React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache. **Implementation:** ```typescript import { LRUCache } from 'lru-cache' const cache = new LRUCache({ max: 1000, ttl: 5 * 60 * 1000 // 5 minutes }) export async function getUser(id: string) { const cached = cache.get(id) if (cached) return cached const user = await db.user.findUnique({ where: { id } }) cache.set(id, user) return user } // Request 1: DB query, result cached // Request 2: cache hit, no DB query ``` Use when sequential user actions hit multiple endpoints needing the same data within seconds. In serverless, consider Redis for cross-process caching. Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache) ### 3.2 Minimize Serialization at RSC Boundaries The React Server/Client boundary serializes all object properties. Only pass fields that the client actually uses. **Incorrect: serializes all 50 fields** ```tsx async function Page() { const user = await fetchUser() // 50 fields return } 'use client' function Profile({ user }: { user: User }) { return

{user.name}

// uses 1 field } ``` **Correct: serializes only 1 field** ```tsx async function Page() { const user = await fetchUser() return } 'use client' function Profile({ name }: { name: string }) { return

{name}

} ``` ### 3.3 Parallel Data Fetching with Component Composition React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching. **Incorrect: Sidebar waits for Page's fetch to complete** ```tsx export default async function Page() { const header = await fetchHeader() return (

{header}

) } async function Sidebar() { const items = await fetchSidebarItems() return } ``` **Correct: both fetch simultaneously** ```tsx async function Header() { const data = await fetchHeader() return

{data}

} async function Sidebar() { const items = await fetchSidebarItems() return } export default function Page() { return (

) } ``` **Alternative with children prop:** ```tsx async function Layout({ children }: { children: ReactNode }) { const header = await fetchHeader() return (

{header}

{children}

) } async function Sidebar() { const items = await fetchSidebarItems() return } export default function Page() { return ( ) } ``` ### 3.4 Per-Request Deduplication with React.cache() Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most. **Usage:** ```typescript import { cache } from 'react' export const getCurrentUser = cache(async () => { const session = await auth() if (!session?.user?.id) return null return await db.user.findUnique({ where: { id: session.user.id } }) }) ``` Within a single request, multiple calls to `getCurrentUser()` execute the query only once. --- ## 4. Client-Side Data Fetching **Impact: MEDIUM-HIGH** Automatic deduplication and efficient data fetching patterns reduce redundant network requests. ### 4.1 Deduplicate Global Event Listeners Use `useSWRSubscription()` to share global event listeners across component instances. **Incorrect: N instances = N listeners** ```tsx function useKeyboardShortcut(key: string, callback: () => void) { useEffect(() => { const handler = (e: KeyboardEvent) => { if (e.metaKey && e.key === key) { callback() } } window.addEventListener('keydown', handler) return () => window.removeEventListener('keydown', handler) }, [key, callback]) } ``` When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener. **Correct: N instances = 1 listener** ```tsx import useSWRSubscription from 'swr/subscription' // Module-level Map to track callbacks per key const keyCallbacks = new Map<string, Set void>>() function useKeyboardShortcut(key: string, callback: () => void) { // Register this callback in the Map useEffect(() => { if (!keyCallbacks.has(key)) { keyCallbacks.set(key, new Set()) } keyCallbacks.get(key)!.add(callback) return () => { const set = keyCallbacks.get(key) if (set) { set.delete(callback) if (set.size === 0) { keyCallbacks.delete(key) } } } }, [key, callback]) useSWRSubscription('global-keydown', () => { const handler = (e: KeyboardEvent) => { if (e.metaKey && keyCallbacks.has(e.key)) { keyCallbacks.get(e.key)!.forEach(cb => cb()) } } window.addEventListener('keydown', handler) return () => window.removeEventListener('keydown', handler) } } function Profile() { // Multiple shortcuts will share the same listener useKeyboardShortcut('p', () => { /* ... */ }) useKeyboardShortcut('k', () => { /* ... */ }) // ... } ``` ### 4.2 Use SWR for Automatic Deduplication SWR enables request deduplication, caching, and revalidation across component instances. **Incorrect: no deduplication, each instance fetches** ```tsx function UserList() { const [users, setUsers] = useState([]) useEffect(() => { fetch('/api/users') .then(r => r.json()) .then(setUsers) }, []) } ``` **Correct: multiple instances share one request** ```tsx import useSWR from 'swr' function UserList() { const { data: users } = useSWR('/api/users', fetcher) } ``` **For immutable data:** ```tsx import { useImmutableSWR } from '@/lib/swr' function StaticContent() { const { data } = useImmutableSWR('/api/config', fetcher) } ``` **For mutations:** ```tsx import { useSWRMutation } from 'swr/mutation' function UpdateButton() { const { trigger } = useSWRMutation('/api/user', updateUser) return } ``` Reference: [https://swr.vercel.app](https://swr.vercel.app) --- ## 5. Re-render Optimization **Impact: MEDIUM** Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness. ### 5.1 Defer State Reads to Usage Point Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks. **Incorrect: subscribes to all searchParams changes** ```tsx function ShareButton({ chatId }: { chatId: string }) { const searchParams = useSearchParams() const handleShare = () => { const ref = searchParams.get('ref') shareChat(chatId, { ref }) } return } ``` **Correct: reads on demand, no subscription** ```tsx function ShareButton({ chatId }: { chatId: string }) { const handleShare = () => { const params = new URLSearchParams(window.location.search) const ref = params.get('ref') shareChat(chatId, { ref }) } return } ``` ### 5.2 Extract to Memoized Components Extract expensive work into memoized components to enable early returns before computation. **Incorrect: computes avatar even when loading** ```tsx function Profile({ user, loading }: Props) { const avatar = useMemo(() => { const id = computeAvatarId(user) return }, [user]) if (loading) return return

{avatar}

} ``` **Correct: skips computation when loading** ```tsx const UserAvatar = memo(function UserAvatar({ user }: { user: User }) { const id = useMemo(() => computeAvatarId(user), [user]) return }) function Profile({ user, loading }: Props) { if (loading) return return (

) } ``` ### 5.3 Narrow Effect Dependencies Specify primitive dependencies instead of objects to minimize effect re-runs. **Incorrect: re-runs on any user field change** ```tsx useEffect(() => { console.log(user.id) }, [user]) ``` **Correct: re-runs only when id changes** ```tsx useEffect(() => { console.log(user.id) }, [user.id]) ``` **For derived state, compute outside effect:** ```tsx // Incorrect: runs on width=767, 766, 765... useEffect(() => { if (width < 768) { enableMobileMode() } }, [width]) // Correct: runs only on boolean transition const isMobile = width { if (isMobile) { enableMobileMode() } }, [isMobile]) ``` ### 5.4 Subscribe to Derived State Subscribe to derived boolean state instead of continuous values to reduce re-render frequency. **Incorrect: re-renders on every pixel change** ```tsx function Sidebar() { const width = useWindowWidth() // updates continuously const isMobile = width < 768 return

} ``` **Correct: re-renders only when boolean changes** ```tsx function Sidebar() { const isMobile = useMediaQuery('(max-width: 767px)') return

} ``` ### 5.5 Use Lazy State Initialization Pass a function to `useState` for expensive initial values. Without the function form, the initializer runs on every render even though the value is only used once. **Incorrect: runs on every render** ```tsx function FilteredList({ items }: { items: Item[] }) { // buildSearchIndex() runs on EVERY render, even after initialization const [searchIndex, setSearchIndex] = useState(buildSearchIndex(items)) const [query, setQuery] = useState('') // When query changes, buildSearchIndex runs again unnecessarily return } function UserProfile() { // JSON.parse runs on every render const [settings, setSettings] = useState( JSON.parse(localStorage.getItem('settings') || '{}') ) return } ``` **Correct: runs only once** ```tsx function FilteredList({ items }: { items: Item[] }) { // buildSearchIndex() runs ONLY on initial render const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items)) const [query, setQuery] = useState('') return } function UserProfile() { // JSON.parse runs only on initial render const [settings, setSettings] = useState(() => { const stored = localStorage.getItem('settings') return stored ? JSON.parse(stored) : {} }) return } ``` Use lazy initialization when computing initial values from localStorage/sessionStorage, building data structures (indexes, maps), reading from the DOM, or performing heavy transformations. For simple primitives (`useState(0)`), direct references (`useState(props.value)`), or cheap literals (`useState({})`), the function form is unnecessary. ### 5.6 Use Transitions for Non-Urgent Updates Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness. **Incorrect: blocks UI on every scroll** ```tsx function ScrollTracker() { const [scrollY, setScrollY] = useState(0) useEffect(() => { const handler = () => setScrollY(window.scrollY) window.addEventListener('scroll', handler, { passive: true }) return () => window.removeEventListener('scroll', handler) }, []) } ``` **Correct: non-blocking updates** ```tsx import { startTransition } from 'react' function ScrollTracker() { const [scrollY, setScrollY] = useState(0) useEffect(() => { const handler = () => { startTransition(() => setScrollY(window.scrollY)) } window.addEventListener('scroll', handler, { passive: true }) return () => window.removeEventListener('scroll', handler) }, []) } ``` --- ## 6. Rendering Performance **Impact: MEDIUM** Optimizing the rendering process reduces the work the browser needs to do. ### 6.1 Animate SVG Wrapper Instead of SVG Element Many browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a `

` and animate the wrapper instead. **Incorrect: animating SVG directly - no hardware acceleration** ```tsx function LoadingSpinner() { return ( ) } ``` **Correct: animating wrapper div - hardware accelerated** ```tsx function LoadingSpinner() { return (

) } ``` This applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations. ### 6.2 CSS content-visibility for Long Lists Apply `content-visibility: auto` to defer off-screen rendering. **CSS:** ```css .message-item { content-visibility: auto; contain-intrinsic-size: 0 80px; } ``` **Example:** ```tsx function MessageList({ messages }: { messages: Message[] }) { return (

{messages.map(msg => (

{msg.content}

))}

) } ``` For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render). ### 6.3 Hoist Static JSX Elements Extract static JSX outside components to avoid re-creation. **Incorrect: recreates element every render** ```tsx function LoadingSkeleton() { return

} function Container() { return (

{loading && }

) } ``` **Correct: reuses same element** ```tsx const loadingSkeleton = (

) function Container() { return (

{loading && loadingSkeleton}

) } ``` This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render. ### 6.4 Optimize SVG Precision Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered. **Incorrect: excessive precision** ```svg ``` **Correct: 1 decimal place** ```svg ``` **Automate with SVGO:** ```bash npx svgo --precision=1 --multipass icon.svg ``` ### 6.5 Prevent Hydration Mismatch Without Flickering When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates. **Incorrect: breaks SSR** ```tsx function ThemeWrapper({ children }: { children: ReactNode }) { // localStorage is not available on server - throws error const theme = localStorage.getItem('theme') || 'light' return (

{children}

) } ``` Server-side rendering will fail because `localStorage` is undefined. **Incorrect: visual flickering** ```tsx function ThemeWrapper({ children }: { children: ReactNode }) { const [theme, setTheme] = useState('light') useEffect(() => { // Runs after hydration - causes visible flash const stored = localStorage.getItem('theme') if (stored) { setTheme(stored) } }, []) return (

{children}

) } ``` Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content. **Correct: no flicker, no hydration mismatch** ```tsx function ThemeWrapper({ children }: { children: ReactNode }) { return (

{children}

` to preserve state/DOM for expensive components that frequently toggle visibility. **Usage:** ```tsx import { Activity } from 'react' function Dropdown({ isOpen }: Props) { return ( ) } ``` Avoids expensive re-renders and state loss. ### 6.7 Use Explicit Conditional Rendering Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render. **Incorrect: renders "0" when count is 0** ```tsx function Badge({ count }: { count: number }) { return (

{count && {count}}

) } // When count = 0, renders:

// When count = 5, renders:

``` **Correct: renders nothing when count is 0** ```tsx function Badge({ count }: { count: number }) { return (

{count > 0 ? {count} : null}

) } // When count = 0, renders:

// When count = 5, renders:

``` --- ## 7. JavaScript Performance **Impact: LOW-MEDIUM** Micro-optimizations for hot paths can add up to meaningful improvements. ### 7.1 Batch DOM CSS Changes Avoid changing styles one property at a time. Group multiple CSS changes together via classes or `cssText` to minimize browser reflows. **Incorrect: multiple reflows** ```typescript function updateElementStyles(element: HTMLElement) { // Each line triggers a reflow element.style.width = '100px' element.style.height = '200px' element.style.backgroundColor = 'blue' element.style.border = '1px solid black' } ``` **Correct: add class - single reflow** ```typescript // CSS file .highlighted-box { width: 100px; height: 200px; background-color: blue; border: 1px solid black; } // JavaScript function updateElementStyles(element: HTMLElement) { element.classList.add('highlighted-box') } ``` **Correct: change cssText - single reflow** ```typescript function updateElementStyles(element: HTMLElement) { element.style.cssText = ` width: 100px; height: 200px; background-color: blue; border: 1px solid black; ` } ``` **React example:** ```tsx // Incorrect: changing styles one by one function Box({ isHighlighted }: { isHighlighted: boolean }) { const ref = useRef(null) useEffect(() => { if (ref.current && isHighlighted) { ref.current.style.width = '100px' ref.current.style.height = '200px' ref.current.style.backgroundColor = 'blue' } }, [isHighlighted]) return

Content

} // Correct: toggle class function Box({ isHighlighted }: { isHighlighted: boolean }) { return (

Content

) } ``` Prefer CSS classes over inline styles when possible. Classes are cached by the browser and provide better separation of concerns. ### 7.2 Build Index Maps for Repeated Lookups Multiple `.find()` calls by the same key should use a Map. **Incorrect (O(n) per lookup):** ```typescript function processOrders(orders: Order[], users: User[]) { return orders.map(order => ({ ...order, user: users.find(u => u.id === order.userId) })) } ``` **Correct (O(1) per lookup):** ```typescript function processOrders(orders: Order[], users: User[]) { const userById = new Map(users.map(u => [u.id, u])) return orders.map(order => ({ ...order, user: userById.get(order.userId) })) } ``` Build map once (O(n)), then all lookups are O(1). For 1000 orders × 1000 users: 1M ops → 2K ops. ### 7.3 Cache Property Access in Loops Cache object property lookups in hot paths. **Incorrect: 3 lookups × N iterations** ```typescript for (let i = 0; i < arr.length; i++) { process(obj.config.settings.value) } ``` **Correct: 1 lookup total** ```typescript const value = obj.config.settings.value const len = arr.length for (let i = 0; i < len; i++) { process(value) } ``` ### 7.4 Cache Repeated Function Calls Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render. **Incorrect: redundant computation** ```typescript function ProjectList({ projects }: { projects: Project[] }) { return (

{projects.map(project => { // slugify() called 100+ times for same project names const slug = slugify(project.name) return })}

) } ``` **Correct: cached results** ```typescript // Module-level cache const cachedSlugify = new Map() function getCachedSlug(text: string): string { if (cachedSlugify.has(text)) { return cachedSlugify.get(text) } const result = slugify(text) cachedSlugify.set(text, result) return result } function ProjectList({ projects }: { projects: Project[] }) { return (

{projects.map(project => { // Computed only once per unique project name const slug = getCachedSlug(project.name) return })}

) } ``` **Simpler pattern for single-value functions:** ```typescript let isLoggedInCache: boolean | null = null function isLoggedIn(): boolean { if (isLoggedInCache !== null) { return isLoggedInCache } isLoggedInCache = document.cookie.includes('auth=') return isLoggedInCache } // Clear cache when auth changes function onAuthChange() { isLoggedInCache = null } ``` Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components. Reference: [https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast) ### 7.5 Cache Storage API Calls `localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory. **Incorrect: reads storage on every call** ```typescript function getTheme() { return localStorage.getItem('theme') ?? 'light' } // Called 10 times = 10 storage reads ``` **Correct: Map cache** ```typescript const storageCache = new Map() function getLocalStorage(key: string) { if (!storageCache.has(key)) { storageCache.set(key, localStorage.getItem(key)) } return storageCache.get(key) } function setLocalStorage(key: string, value: string) { localStorage.setItem(key, value) storageCache.set(key, value) // keep cache in sync } ``` Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components. **Cache invalidation:** ```typescript window.addEventListener('storage', (e) => { if (e.key) storageCache.delete(e.key) }) document.addEventListener('visibilitychange', () => { if (document.visibilityState === 'visible') { storageCache.clear() } }) ``` ### 7.6 Combine Multiple Array Iterations Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop. **Incorrect: 3 iterations** ```typescript const admins = users.filter(u => u.isAdmin) const testers = users.filter(u => u.isTester) const inactive = users.filter(u => !u.isActive) ``` **Correct: 1 iteration** ```typescript const admins: User[] = [] const testers: User[] = [] const inactive: User[] = [] for (const user of users) { if (user.isAdmin) admins.push(user) if (user.isTester) testers.push(user) if (!user.isActive) inactive.push(user) } ``` ### 7.7 Early Length Check for Array Comparisons When comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal. In real-world applications, this optimization is especially valuable when the comparison runs in hot paths (event handlers, render loops). **Incorrect: always runs expensive comparison** ```typescript function hasChanges(current: string[], original: string[]) { // Always sorts and joins, even when lengths differ return current.sort().join() !== original.sort().join() } ``` Two O(n log n) sorts run even when `current.length` is 5 and `original.length` is 100. **Correct (O(1) length check first):** ```typescript function hasChanges(current: string[], original: string[]) { // Early return if lengths differ if (current.length !== original.length) { return true } // Only sort when lengths match const currentSorted = current.toSorted() const originalSorted = original.toSorted() for (let i = 0; i < currentSorted.length; i++) { if (currentSorted[i] !== originalSorted[i]) { return true } } return false } ``` This approach avoids sorting when lengths differ, avoiding both computational overhead and memory consumption for joined strings. ### 7.8 Early Return from Functions Return early when result is determined to skip unnecessary processing. **Incorrect: processes all items even after finding answer** ```typescript function validateUsers(users: User[]) { let hasError = false let errorMessage = '' for (const user of users) { if (!user.email) { hasError = true errorMessage = 'Email required' } if (!user.name) { hasError = true errorMessage = 'Name required' } // Continues checking all users even after error found } return hasError ? { valid: false, error: errorMessage } : { valid: true } } ``` **Correct: returns immediately on first error** ```typescript function validateUsers(users: User[]) { for (const user of users) { if (!user.email) { return { valid: false, error: 'Email required' } } if (!user.name) { return { valid: false, error: 'Name required' } } } return { valid: true } } ``` ### 7.9 Hoist RegExp Creation Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`. **Incorrect: new RegExp every render** ```tsx function Highlighter({ text, query }: Props) { const regex = new RegExp(`(${query})`, 'gi') const parts = text.split(regex) return {parts.map((part, i) => ...)} b.updatedAt - a.updatedAt) return sorted[0] } ``` **Correct (O(n) - single loop):** ```typescript function getLatestProject(projects: Project[]) { if (projects.length === 0) return null let latest = projects[0] for (let i = 1; i latest.updatedAt) { latest = projects[i] } } return latest } function getOldestAndNewest(projects: Project[]) { if (projects.length === 0) return { oldest: null, newest: null } let oldest = projects[0] let newest = projects[0] for (let i = 1; i < projects.length; i++) { if (projects[i].updatedAt newest.updatedAt) newest = projects[i] } return { oldest, newest } } ``` Single pass through the array, no copying, no sorting. ### 7.11 Use Set/Map for O(1) Lookups Convert arrays to Set/Map for repeated membership checks. **Incorrect (O(n) per check):** ```typescript const allowedIds = ['a', 'b', 'c', ...] items.filter(item => allowedIds.includes(item.id)) ``` **Correct (O(1) per check):** ```typescript const allowedIds = new Set(['a', 'b', 'c', ...]) items.filter(item => allowedIds.has(item.id)) ``` ### 7.12 Use toSorted() Instead of sort() for Immutability `.sort()` mutates the array in place, which can cause bugs with React state and props. Use `.toSorted()` to create a new sorted array without mutation. **Incorrect: mutates original array** ```typescript function UserList({ users }: { users: User[] }) { // Mutates the users prop array! const sorted = useMemo( () => users.sort((a, b) => a.name.localeCompare(b.name)), [users] ) return

{sorted.map(renderUser)}

} ``` **Correct: creates new array** ```typescript function UserList({ users }: { users: User[] }) { // Creates new sorted array, original unchanged const sorted = useMemo( () => users.toSorted((a, b) => a.name.localeCompare(b.name)), [users] ) return

{sorted.map(renderUser)}

} ``` **Browser support fallback:** ```typescript const sorted = [...items].sort((a, b) => a.value - b.value) ``` --- ## 8. Advanced Patterns **Impact: LOW** Advanced patterns for specific cases that require careful implementation. ### 8.1 Store Event Handlers in Refs Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes. **Incorrect: re-subscribes on every render** ```tsx function useWindowEvent(event: string, handler: () => void) { useEffect(() => { window.addEventListener(event, handler) return () => window.removeEventListener(event, handler) }, [event, handler]) } ``` **Correct: stable subscription** ```tsx function useWindowEvent(event: string, handler: () => void) { const handlerRef = useRef(handler) useEffect(() => { handlerRef.current = handler }, [handler]) useEffect(() => { const listener = () => handlerRef.current() window.addEventListener(event, listener) return () => window.removeEventListener(event, listener) }, [event]) } ``` ### 8.2 useLatest for Stable Callback Refs Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures. **Implementation:** ```typescript function useLatest(value: T) { const ref = useRef(value) useEffect(() => { ref.current = value }, [value]) return ref } ``` **Incorrect: effect re-runs on every callback change** ```tsx function SearchInput({ onSearch }: { onSearch: (q: string) => void }) { const [query, setQuery] = useState('') useEffect(() => { const timeout = setTimeout(() => onSearch(query), 300) return () => clearTimeout(timeout) }, [query, onSearch]) } ``` **Correct: stable effect, fresh callback** ```tsx function SearchInput({ onSearch }: { onSearch: (q: string) => void }) { const [query, setQuery] = useState('') const onSearchRef = useLatest(onSearch) useEffect(() => { const timeout = setTimeout(() => onSearchRef.current(query), 300) return () => clearTimeout(timeout) }, [query]) } ``` --- ## References 1. [https://react.dev](https://react.dev) 2. [https://nextjs.org](https://nextjs.org) 3. [https://swr.vercel.app](https://swr.vercel.app) 4. [https://github.com/shuding/better-all](https://github.com/shuding/better-all) 5. [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache) 6. [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js) 7. [https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)

Source: claude-code-templates (MIT). See About Us for full credits.

BAGUA AI