React Best Practices

React Best Practices - Performance Optimization

Comprehensive performance optimization guide for React and Next.js applications with 40+ rules organized by impact level. Designed to help developers eliminate performance bottlenecks and follow best practices.

When to use this skill

Use React Best Practices when:

• Optimizing React or Next.js application performance
• Reviewing code for performance improvements
• Refactoring existing components for better performance
• Implementing new features with performance in mind
• Debugging slow rendering or loading issues
• Reducing bundle size
• Eliminating request waterfalls

Key areas covered:

• Eliminating Waterfalls (CRITICAL): Prevent sequential async operations
• Bundle Size Optimization (CRITICAL): Reduce initial JavaScript payload
• Server-Side Performance (HIGH): Optimize RSC and data fetching
• Client-Side Data Fetching (MEDIUM-HIGH): Implement efficient caching
• Re-render Optimization (MEDIUM): Minimize unnecessary re-renders
• Rendering Performance (MEDIUM): Optimize browser rendering
• JavaScript Performance (LOW-MEDIUM): Micro-optimizations for hot paths
• Advanced Patterns (LOW): Specialized techniques for edge cases

Quick reference

Critical priorities

1. Defer await until needed - Move awaits into branches where they're used 2. Use Promise.all() - Parallelize independent async operations 3. Avoid barrel imports - Import directly from source files 4. Dynamic imports - Lazy-load heavy components 5. Strategic Suspense - Stream content while showing layout

Common patterns

Parallel data fetching:

const [user, posts, comments] = await Promise.all([
  fetchUser(),
  fetchPosts(),
  fetchComments()
])

Direct imports:

// ❌ Loads entire library
import { Check } from 'lucide-react'

// ✅ Loads only what you need
import Check from 'lucide-react/dist/esm/icons/check'

Dynamic components:

import dynamic from 'next/dynamic'

const MonacoEditor = dynamic(
  () => import('./monaco-editor'),
  { ssr: false }
)

Using the guidelines

The complete performance guidelines are available in the references folder:

• react-performance-guidelines.md: Complete guide with all 40+ rules, code examples, and impact analysis

Each rule includes:

• Incorrect/correct code comparisons
• Specific impact metrics
• When to apply the optimization
• Real-world examples

Categories overview

1. Eliminating Waterfalls (CRITICAL)

Waterfalls are the #1 performance killer. Each sequential await adds full network latency.

• Defer await until needed
• Dependency-based parallelization
• Prevent waterfall chains in API routes
• Promise.all() for independent operations
• Strategic Suspense boundaries

2. Bundle Size Optimization (CRITICAL)

Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.

• Avoid barrel file imports
• Conditional module loading
• Defer non-critical third-party libraries
• Dynamic imports for heavy components
• Preload based on user intent

3. Server-Side Performance (HIGH)

Optimize server-side rendering and data fetching.

• Cross-request LRU caching
• Minimize serialization at RSC boundaries
• Parallel data fetching with component composition
• Per-request deduplication with React.cache()

4. Client-Side Data Fetching (MEDIUM-HIGH)

Automatic deduplication and efficient data fetching patterns.

• Deduplicate global event listeners
• Use SWR for automatic deduplication

5. Re-render Optimization (MEDIUM)

Reduce unnecessary re-renders to minimize wasted computation.

• Defer state reads to usage point
• Extract to memoized components
• Narrow effect dependencies
• Subscribe to derived state
• Use lazy state initialization
• Use transitions for non-urgent updates

6. Rendering Performance (MEDIUM)

Optimize the browser rendering process.

• Animate SVG wrapper instead of SVG element
• CSS content-visibility for long lists
• Hoist static JSX elements
• Optimize SVG precision
• Prevent hydration mismatch without flickering
• Use Activity component for show/hide
• Use explicit conditional rendering

7. JavaScript Performance (LOW-MEDIUM)

Micro-optimizations for hot paths.

• Batch DOM CSS changes
• Build index maps for repeated lookups
• Cache property access in loops
• Cache repeated function calls
• Cache storage API calls
• Combine multiple array iterations
• Early length check for array comparisons
• Early return from functions
• Hoist RegExp creation
• Use loop for min/max instead of sort
• Use Set/Map for O(1) lookups
• Use toSorted() instead of sort()

8. Advanced Patterns (LOW)

Specialized techniques for edge cases.

• Store event handlers in refs
• useLatest for stable callback refs

Implementation approach

When optimizing a React application:

1. Profile first: Use React DevTools Profiler and browser performance tools to identify bottlenecks 2. Focus on critical paths: Start with eliminating waterfalls and reducing bundle size 3. Measure impact: Verify improvements with metrics (LCP, TTI, FID) 4. Apply incrementally: Don't over-optimize prematurely 5. Test thoroughly: Ensure optimizations don't break functionality

Key metrics to track

• Time to Interactive (TTI): When page becomes fully interactive
• Largest Contentful Paint (LCP): When main content is visible
• First Input Delay (FID): Responsiveness to user interactions
• Cumulative Layout Shift (CLS): Visual stability
• Bundle size: Initial JavaScript payload
• Server response time: TTFB for server-rendered content

Common pitfalls to avoid

❌ Don't:

• Use barrel imports from large libraries
• Block parallel operations with sequential awaits
• Re-render entire trees when only part needs updating
• Load analytics/tracking in the critical path
• Mutate arrays with .sort() instead of .toSorted()
• Create RegExp or heavy objects inside render

✅ Do:

• Import directly from source files
• Use Promise.all() for independent operations
• Memoize expensive components
• Lazy-load non-critical code
• Use immutable array methods
• Hoist static objects outside components

Resources

• React Documentation
• Next.js Documentation
• SWR Documentation
• Vercel Bundle Optimization
• Vercel Dashboard Performance
• better-all Library
• node-lru-cache

Version history

v0.1.0 (January 2026)

• Initial release from Vercel Engineering
• 40+ performance rules across 8 categories
• Comprehensive code examples and impact analysis

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 — CRITICAL

• 1.1 Defer Await Until Needed
• 1.2 Dependency-Based Parallelization
• 1.3 Prevent Waterfall Chains in API Routes
• 1.4 Promise.all() for Independent Operations
• 1.5 Strategic Suspense Boundaries

2. Bundle Size Optimization — CRITICAL

• 2.1 Avoid Barrel File Imports
• 2.2 Conditional Module Loading
• 2.3 Defer Non-Critical Third-Party Libraries
• 2.4 Dynamic Imports for Heavy Components
• 2.5 Preload Based on User Intent

3. Server-Side Performance — HIGH

• 3.1 Cross-Request LRU Caching
• 3.2 Minimize Serialization at RSC Boundaries
• 3.3 Parallel Data Fetching with Component Composition
• 3.4 Per-Request Deduplication with React.cache()

4. Client-Side Data Fetching — MEDIUM-HIGH

• 4.1 Deduplicate Global Event Listeners
• 4.2 Use SWR for Automatic Deduplication

5. Re-render Optimization — MEDIUM

• 5.1 Defer State Reads to Usage Point
• 5.2 Extract to Memoized Components
• 5.3 Narrow Effect Dependencies
• 5.4 Subscribe to Derived State
• 5.5 Use Lazy State Initialization
• 5.6 Use Transitions for Non-Urgent Updates

6. Rendering Performance — MEDIUM

• 6.1 Animate SVG Wrapper Instead of SVG Element
• 6.2 CSS content-visibility for Long Lists
• 6.3 Hoist Static JSX Elements
• 6.4 Optimize SVG Precision
• 6.5 Prevent Hydration Mismatch Without Flickering
• 6.6 Use Activity Component for Show/Hide
• 6.7 Use Explicit Conditional Rendering

7. JavaScript Performance — LOW-MEDIUM

• 7.1 Batch DOM CSS Changes
• 7.2 Build Index Maps for Repeated Lookups
• 7.3 Cache Property Access in Loops
• 7.4 Cache Repeated Function Calls
• 7.5 Cache Storage API Calls
• 7.6 Combine Multiple Array Iterations
• 7.7 Early Length Check for Array Comparisons
• 7.8 Early Return from Functions
• 7.9 Hoist RegExp Creation
• 7.10 Use Loop for Min/Max Instead of Sort
• 7.11 Use Set/Map for O(1) Lookups
• 7.12 Use toSorted() Instead of sort() for Immutability

8. Advanced Patterns — LOW

• 8.1 Store Event Handlers in Refs
• 8.2 useLatest for Stable Callback Refs

---

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

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

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

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

const [user, config] = await Promise.all([
  fetchUser(),
  fetchConfig()
])
const profile = await fetchProfile(user.id)

Correct: config and profile run in parallel

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

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

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

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

const user = await fetchUser()
const posts = await fetchPosts()
const comments = await fetchComments()

Correct: parallel execution, 1 round trip

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

async function Page() {
  const data = await fetchData() // Blocks entire page

  return (
    <div>
      <div>Sidebar</div>
      <div>Header</div>
      <div>
        <DataDisplay data={data} />
      </div>
      <div>Footer</div>
    </div>
  )
}

The entire layout waits for data even though only the middle section needs it.

Correct: wrapper shows immediately, data streams in

function Page() {
  return (
    <div>
      <div>Sidebar</div>
      <div>Header</div>
      <div>
        <Suspense fallback={<Skeleton />}>
          <DataDisplay />
        </Suspense>
      </div>
      <div>Footer</div>
    </div>
  )
}

async function DataDisplay() {
  const data = await fetchData() // Only blocks this component
  return <div>{data.content}</div>
}

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

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

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+

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

2.2 Conditional Module Loading

Load large data or modules only when a feature is activated.

Example: lazy-load animation frames

function AnimationPlayer({ enabled }: { enabled: boolean }) {
  const [frames, setFrames] = useState<Frame[] | null>(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 <Skeleton />
  return <Canvas frames={frames} />
}

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

import { Analytics } from '@vercel/analytics/react'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Analytics />
      </body>
    </html>
  )
}

Correct: loads after hydration

import dynamic from 'next/dynamic'

const Analytics = dynamic(
  () => import('@vercel/analytics/react').then(m => m.Analytics),
  { ssr: false }
)

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Analytics />
      </body>
    </html>
  )
}

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

import { MonacoEditor } from './monaco-editor'

function CodePanel({ code }: { code: string }) {
  return <MonacoEditor value={code} />
}

Correct: Monaco loads on demand

import dynamic from 'next/dynamic'

const MonacoEditor = dynamic(
  () => import('./monaco-editor').then(m => m.MonacoEditor),
  { ssr: false }
)

function CodePanel({ code }: { code: string }) {
  return <MonacoEditor value={code} />
}

2.5 Preload Based on User Intent

Preload heavy bundles before they're needed to reduce perceived latency.

Example: preload on hover/focus

function EditorButton({ onClick }: { onClick: () => void }) {
  const preload = () => {
    if (typeof window !== 'undefined') {
      void import('./monaco-editor')
    }
  }

  return (
    <button
      onMouseEnter={preload}
      onFocus={preload}
      onClick={onClick}
    >
      Open Editor
    </button>
  )
}

Example: preload when feature flag is enabled

function FlagsProvider({ children, flags }: Props) {
  useEffect(() => {
    if (flags.editorEnabled && typeof window !== 'undefined') {
      void import('./monaco-editor').then(mod => mod.init())
    }
  }, [flags.editorEnabled])

  return <FlagsContext.Provider value={flags}>
    {children}
  </FlagsContext.Provider>
}

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:

import { LRUCache } from 'lru-cache'

const cache = new LRUCache<string, any>({
  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

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

async function Page() {
  const user = await fetchUser()  // 50 fields
  return <Profile user={user} />
}

'use client'
function Profile({ user }: { user: User }) {
  return <div>{user.name}</div>  // uses 1 field
}

Correct: serializes only 1 field

async function Page() {
  const user = await fetchUser()
  return <Profile name={user.name} />
}

'use client'
function Profile({ name }: { name: string }) {
  return <div>{name}</div>
}

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

export default async function Page() {
  const header = await fetchHeader()
  return (
    <div>
      <div>{header}</div>
      <Sidebar />
    </div>
  )
}

async function Sidebar() {
  const items = await fetchSidebarItems()
  return <nav>{items.map(renderItem)}</nav>
}

Correct: both fetch simultaneously

async function Header() {
  const data = await fetchHeader()
  return <div>{data}</div>
}

async function Sidebar() {
  const items = await fetchSidebarItems()
  return <nav>{items.map(renderItem)}</nav>
}

export default function Page() {
  return (
    <div>
      <Header />
      <Sidebar />
    </div>
  )
}

Alternative with children prop:

async function Layout({ children }: { children: ReactNode }) {
  const header = await fetchHeader()
  return (
    <div>
      <div>{header}</div>
      {children}
    </div>
  )
}

async function Sidebar() {
  const items = await fetchSidebarItems()
  return <nav>{items.map(renderItem)}</nav>
}

export default function Page() {
  return (
    <Layout>
      <Sidebar />
    </Layout>
  )
}

3.4 Per-Request Deduplication with React.cache()

Use React.cache() for server-side request deduplication. Authentication and database queries benefit most.

Usage:

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

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

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

function UserList() {
  const [users, setUsers] = useState([])
  useEffect(() => {
    fetch('/api/users')
      .then(r => r.json())
      .then(setUsers)
  }, [])
}

Correct: multiple instances share one request

import useSWR from 'swr'

function UserList() {
  const { data: users } = useSWR('/api/users', fetcher)
}

For immutable data:

import { useImmutableSWR } from '@/lib/swr'

function StaticContent() {
  const { data } = useImmutableSWR('/api/config', fetcher)
}

For mutations:

import { useSWRMutation } from 'swr/mutation'

function UpdateButton() {
  const { trigger } = useSWRMutation('/api/user', updateUser)
  return <button onClick={() => trigger()}>Update</button>
}

Reference: 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

function ShareButton({ chatId }: { chatId: string }) {
  const searchParams = useSearchParams()

  const handleShare = () => {
    const ref = searchParams.get('ref')
    shareChat(chatId, { ref })
  }

  return <button onClick={handleShare}>Share</button>
}

Correct: reads on demand, no subscription

function ShareButton({ chatId }: { chatId: string }) {
  const handleShare = () => {
    const params = new URLSearchParams(window.location.search)
    const ref = params.get('ref')
    shareChat(chatId, { ref })
  }

  return <button onClick={handleShare}>Share</button>
}

5.2 Extract to Memoized Components

Extract expensive work into memoized components to enable early returns before computation.

Incorrect: computes avatar even when loading

function Profile({ user, loading }: Props) {
  const avatar = useMemo(() => {
    const id = computeAvatarId(user)
    return <Avatar id={id} />
  }, [user])

  if (loading) return <Skeleton />
  return <div>{avatar}</div>
}

Correct: skips computation when loading

const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
  const id = useMemo(() => computeAvatarId(user), [user])
  return <Avatar id={id} />
})

function Profile({ user, loading }: Props) {
  if (loading) return <Skeleton />
  return (
    <div>
      <UserAvatar user={user} />
    </div>
  )
}

5.3 Narrow Effect Dependencies

Specify primitive dependencies instead of objects to minimize effect re-runs.

Incorrect: re-runs on any user field change

useEffect(() => {
  console.log(user.id)
}, [user])

Correct: re-runs only when id changes

useEffect(() => {
  console.log(user.id)
}, [user.id])

For derived state, compute outside effect:

// Incorrect: runs on width=767, 766, 765...
useEffect(() => {
  if (width < 768) {
    enableMobileMode()
  }
}, [width])

// Correct: runs only on boolean transition
const isMobile = width < 768
useEffect(() => {
  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

function Sidebar() {
  const width = useWindowWidth()  // updates continuously
  const isMobile = width < 768
  return <nav className={isMobile ? 'mobile' : 'desktop'}>
}

Correct: re-renders only when boolean changes

function Sidebar() {
  const isMobile = useMediaQuery('(max-width: 767px)')
  return <nav className={isMobile ? 'mobile' : 'desktop'}>
}

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

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 <SearchResults index={searchIndex} query={query} />
}

function UserProfile() {
  // JSON.parse runs on every render
  const [settings, setSettings] = useState(
    JSON.parse(localStorage.getItem('settings') || '{}')
  )

  return <SettingsForm settings={settings} onChange={setSettings} />
}

Correct: runs only once

function FilteredList({ items }: { items: Item[] }) {
  // buildSearchIndex() runs ONLY on initial render
  const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items))
  const [query, setQuery] = useState('')

  return <SearchResults index={searchIndex} query={query} />
}

function UserProfile() {
  // JSON.parse runs only on initial render
  const [settings, setSettings] = useState(() => {
    const stored = localStorage.getItem('settings')
    return stored ? JSON.parse(stored) : {}
  })

  return <SettingsForm settings={settings} onChange={setSettings} />
}

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

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

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 <div> and animate the wrapper instead.

Incorrect: animating SVG directly - no hardware acceleration

function LoadingSpinner() {
  return (
    <svg
      className="animate-spin"
      width="24"
      height="24"
      viewBox="0 0 24 24"
    >
      <circle cx="12" cy="12" r="10" stroke="currentColor" />
    </svg>
  )
}

Correct: animating wrapper div - hardware accelerated

function LoadingSpinner() {
  return (
    <div className="animate-spin">
      <svg
        width="24"
        height="24"
        viewBox="0 0 24 24"
      >
        <circle cx="12" cy="12" r="10" stroke="currentColor" />
      </svg>
    </div>
  )
}

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:

.message-item {
  content-visibility: auto;
  contain-intrinsic-size: 0 80px;
}

Example:

function MessageList({ messages }: { messages: Message[] }) {
  return (
    <div className="overflow-y-auto h-screen">
      {messages.map(msg => (
        <div key={msg.id} className="message-item">
          <Avatar user={msg.author} />
          <div>{msg.content}</div>
        </div>
      ))}
    </div>
  )
}

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

function LoadingSkeleton() {
  return <div className="animate-pulse h-20 bg-gray-200" />
}

function Container() {
  return (
    <div>
      {loading && <LoadingSkeleton />}
    </div>
  )
}

Correct: reuses same element

const loadingSkeleton = (
  <div className="animate-pulse h-20 bg-gray-200" />
)

function Container() {
  return (
    <div>
      {loading && loadingSkeleton}
    </div>
  )
}

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

<path d="M 10.293847 20.847362 L 30.938472 40.192837" />

Correct: 1 decimal place

<path d="M 10.3 20.8 L 30.9 40.2" />

Automate with SVGO:

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

function ThemeWrapper({ children }: { children: ReactNode }) {
  // localStorage is not available on server - throws error
  const theme = localStorage.getItem('theme') || 'light'

  return (
    <div className={theme}>
      {children}
    </div>
  )
}

Server-side rendering will fail because localStorage is undefined.

Incorrect: visual flickering

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 (
    <div className={theme}>
      {children}
    </div>
  )
}

Component first renders with default value (light), then updates after hydration, causing a visible flash of incorrect content.

Correct: no flicker, no hydration mismatch

function ThemeWrapper({ children }: { children: ReactNode }) {
  return (
    <>
      <div id="theme-wrapper">
        {children}
      </div>
      <script
        dangerouslySetInnerHTML={{
          __html: `
            (function() {
              try {
                var theme = localStorage.getItem('theme') || 'light';
                var el = document.getElementById('theme-wrapper');
                if (el) el.className = theme;
              } catch (e) {}
            })();
          `,
        }}
      />
    </>
  )
}

The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.

This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.

6.6 Use Activity Component for Show/Hide

Use React's <Activity> to preserve state/DOM for expensive components that frequently toggle visibility.

Usage:

import { Activity } from 'react'

function Dropdown({ isOpen }: Props) {
  return (
    <Activity mode={isOpen ? 'visible' : 'hidden'}>
      <ExpensiveMenu />
    </Activity>
  )
}

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

function Badge({ count }: { count: number }) {
  return (
    <div>
      {count && <span className="badge">{count}</span>}
    </div>
  )
}

// When count = 0, renders: <div>0</div>
// When count = 5, renders: <div><span class="badge">5</span></div>

Correct: renders nothing when count is 0

function Badge({ count }: { count: number }) {
  return (
    <div>
      {count > 0 ? <span className="badge">{count}</span> : null}
    </div>
  )
}

// When count = 0, renders: <div></div>
// When count = 5, renders: <div><span class="badge">5</span></div>

---

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

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

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

function updateElementStyles(element: HTMLElement) {
  element.style.cssText = `
    width: 100px;
    height: 200px;
    background-color: blue;
    border: 1px solid black;
  `
}

React example:

// Incorrect: changing styles one by one
function Box({ isHighlighted }: { isHighlighted: boolean }) {
  const ref = useRef<HTMLDivElement>(null)

  useEffect(() => {
    if (ref.current && isHighlighted) {
      ref.current.style.width = '100px'
      ref.current.style.height = '200px'
      ref.current.style.backgroundColor = 'blue'
    }
  }, [isHighlighted])

  return <div ref={ref}>Content</div>
}

// Correct: toggle class
function Box({ isHighlighted }: { isHighlighted: boolean }) {
  return (
    <div className={isHighlighted ? 'highlighted-box' : ''}>
      Content
    </div>
  )
}

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):

function processOrders(orders: Order[], users: User[]) {
  return orders.map(order => ({
    ...order,
    user: users.find(u => u.id === order.userId)
  }))
}

Correct (O(1) per lookup):

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

for (let i = 0; i < arr.length; i++) {
  process(obj.config.settings.value)
}

Correct: 1 lookup total

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

function ProjectList({ projects }: { projects: Project[] }) {
  return (
    <div>
      {projects.map(project => {
        // slugify() called 100+ times for same project names
        const slug = slugify(project.name)

        return <ProjectCard key={project.id} slug={slug} />
      })}
    </div>
  )
}

Correct: cached results

// Module-level cache
const cachedSlugify = new Map<string, any>()

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 (
    <div>
      {projects.map(project => {
        // Computed only once per unique project name
        const slug = getCachedSlug(project.name)

        return <ProjectCard key={project.id} slug={slug} />
      })}
    </div>
  )
}

Simpler pattern for single-value functions:

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

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

function getTheme() {
  return localStorage.getItem('theme') ?? 'light'
}
// Called 10 times = 10 storage reads

Correct: Map cache

const storageCache = new Map<string, string | null>()

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:

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

const admins = users.filter(u => u.isAdmin)
const testers = users.filter(u => u.isTester)
const inactive = users.filter(u => !u.isActive)

Correct: 1 iteration

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

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):

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

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

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

function Highlighter({ text, query }: Props) {
  const regex = new RegExp(`(${query})`, 'gi')
  const parts = text.split(regex)
  return <>{parts.map((part, i) => ...)}</>
}

Correct: memoize or hoist

const regex = /foo/g

Note: RegExp with global flag (g) has stateful lastIndex. Cache and reset as needed.

7.10 Use Loop for Min/Max Instead of Sort

Finding the smallest or largest element only requires a single pass. Sorting is wasteful.

Incorrect (O(n log n) - sort to find latest):

interface Project {
  id: string
  name: string
  updatedAt: number
}

function getLatestProject(projects: Project[]) {
  const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
  return sorted[0]
}

Correct (O(n) - single loop):

function getLatestProject(projects: Project[]) {
  if (projects.length === 0) return null

  let latest = projects[0]

  for (let i = 1; i < projects.length; i++) {
    if (projects[i].updatedAt > 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 < oldest.updatedAt) oldest = projects[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):

const allowedIds = ['a', 'b', 'c', ...]
items.filter(item => allowedIds.includes(item.id))

Correct (O(1) per check):

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

function UserList({ users }: { users: User[] }) {
  // Mutates the users prop array!
  const sorted = useMemo(
    () => users.sort((a, b) => a.name.localeCompare(b.name)),
    [users]
  )
  return <div>{sorted.map(renderUser)}</div>
}

Correct: creates new array

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 <div>{sorted.map(renderUser)}</div>
}

Browser support fallback:

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

function useWindowEvent(event: string, handler: () => void) {
  useEffect(() => {
    window.addEventListener(event, handler)
    return () => window.removeEventListener(event, handler)
  }, [event, handler])
}

Correct: stable subscription

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:

function useLatest<T>(value: T) {
  const ref = useRef(value)
  useEffect(() => {
    ref.current = value
  }, [value])
  return ref
}

Incorrect: effect re-runs on every callback change

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

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 2. https://nextjs.org 3. https://swr.vercel.app 4. https://github.com/shuding/better-all 5. https://github.com/isaacs/node-lru-cache 6. 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

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. Eliminating Waterfalls (async)

Impact: CRITICAL Description: Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.

2. Bundle Size Optimization (bundle)

Impact: CRITICAL Description: Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.

3. Server-Side Performance (server)

Impact: HIGH Description: Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.

4. Client-Side Data Fetching (client)

Impact: MEDIUM-HIGH Description: Automatic deduplication and efficient data fetching patterns reduce redundant network requests.

5. Re-render Optimization (rerender)

Impact: MEDIUM Description: Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.

6. Rendering Performance (rendering)

Impact: MEDIUM Description: Optimizing the rendering process reduces the work the browser needs to do.

7. JavaScript Performance (js)

Impact: LOW-MEDIUM Description: Micro-optimizations for hot paths can add up to meaningful improvements.

8. Advanced Patterns (advanced)

Impact: LOW Description: Advanced patterns for specific cases that require careful implementation.

Rule Title Here

Impact: MEDIUM (optional impact description)

Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.

Incorrect (description of what's wrong):

// Bad code example here
const bad = example()

Correct (description of what's right):

// Good code example here
const good = example()

Reference: Link to documentation or resource

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):

function useWindowEvent(event: string, handler: () => void) {
  useEffect(() => {
    window.addEventListener(event, handler)
    return () => window.removeEventListener(event, handler)
  }, [event, handler])
}

Correct (stable subscription):

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])
}

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:

function useLatest<T>(value: T) {
  const ref = useRef(value)
  useEffect(() => {
    ref.current = value
  }, [value])
  return ref
}

Incorrect (effect re-runs on every callback change):

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):

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])
}

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):

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):

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

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):

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):

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):

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

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):

const [user, config] = await Promise.all([
  fetchUser(),
  fetchConfig()
])
const profile = await fetchProfile(user.id)

Correct (config and profile run in parallel):

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

Promise.all() for Independent Operations

When async operations have no interdependencies, execute them concurrently using Promise.all().

Incorrect (sequential execution, 3 round trips):

const user = await fetchUser()
const posts = await fetchPosts()
const comments = await fetchComments()

Correct (parallel execution, 1 round trip):

const [user, posts, comments] = await Promise.all([
  fetchUser(),
  fetchPosts(),
  fetchComments()
])

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):

async function Page() {
  const data = await fetchData() // Blocks entire page
  
  return (
    <div>
      <div>Sidebar</div>
      <div>Header</div>
      <div>
        <DataDisplay data={data} />
      </div>
      <div>Footer</div>
    </div>
  )
}

The entire layout waits for data even though only the middle section needs it.

Correct (wrapper shows immediately, data streams in):

function Page() {
  return (
    <div>
      <div>Sidebar</div>
      <div>Header</div>
      <div>
        <Suspense fallback={<Skeleton />}>
          <DataDisplay />
        </Suspense>
      </div>
      <div>Footer</div>
    </div>
  )
}

async function DataDisplay() {
  const data = await fetchData() // Only blocks this component
  return <div>{data.content}</div>
}

Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.

When NOT to use this pattern:

• Critical data needed for layout decisions (affects positioning)
• SEO-critical content above the fold
• Small, fast queries where suspense overhead isn't worth it
• When you want to avoid layout shift (loading → content jump)

Trade-off: Faster initial paint vs potential layout shift. Choose based on your UX priorities.

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.

Why tree-shaking doesn't help: When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.

Incorrect (imports entire library):

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):

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+):

// 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: How we optimized package imports in Next.js

Conditional Module Loading

Load large data or modules only when a feature is activated.

Example (lazy-load animation frames):

function AnimationPlayer({ enabled }: { enabled: boolean }) {
  const [frames, setFrames] = useState<Frame[] | null>(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 <Skeleton />
  return <Canvas frames={frames} />
}

The typeof window !== 'undefined' check prevents bundling this module for SSR, optimizing server bundle size and build speed.

Defer Non-Critical Third-Party Libraries

Analytics, logging, and error tracking don't block user interaction. Load them after hydration.

Incorrect (blocks initial bundle):

import { Analytics } from '@vercel/analytics/react'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Analytics />
      </body>
    </html>
  )
}

Correct (loads after hydration):

import dynamic from 'next/dynamic'

const Analytics = dynamic(
  () => import('@vercel/analytics/react').then(m => m.Analytics),
  { ssr: false }
)

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Analytics />
      </body>
    </html>
  )
}

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):

import { MonacoEditor } from './monaco-editor'

function CodePanel({ code }: { code: string }) {
  return <MonacoEditor value={code} />
}

Correct (Monaco loads on demand):

import dynamic from 'next/dynamic'

const MonacoEditor = dynamic(
  () => import('./monaco-editor').then(m => m.MonacoEditor),
  { ssr: false }
)

function CodePanel({ code }: { code: string }) {
  return <MonacoEditor value={code} />
}

Preload Based on User Intent

Preload heavy bundles before they're needed to reduce perceived latency.

Example (preload on hover/focus):

function EditorButton({ onClick }: { onClick: () => void }) {
  const preload = () => {
    if (typeof window !== 'undefined') {
      void import('./monaco-editor')
    }
  }

  return (
    <button
      onMouseEnter={preload}
      onFocus={preload}
      onClick={onClick}
    >
      Open Editor
    </button>
  )
}

Example (preload when feature flag is enabled):

function FlagsProvider({ children, flags }: Props) {
  useEffect(() => {
    if (flags.editorEnabled && typeof window !== 'undefined') {
      void import('./monaco-editor').then(mod => mod.init())
    }
  }, [flags.editorEnabled])

  return <FlagsContext.Provider value={flags}>
    {children}
  </FlagsContext.Provider>
}

The typeof window !== 'undefined' check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.

Deduplicate Global Event Listeners

Use useSWRSubscription() to share global event listeners across component instances.

Incorrect (N instances = N listeners):

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):

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', () => { /* ... */ })
  // ...
}

Use SWR for Automatic Deduplication

SWR enables request deduplication, caching, and revalidation across component instances.

Incorrect (no deduplication, each instance fetches):

function UserList() {
  const [users, setUsers] = useState([])
  useEffect(() => {
    fetch('/api/users')
      .then(r => r.json())
      .then(setUsers)
  }, [])
}

Correct (multiple instances share one request):

import useSWR from 'swr'

function UserList() {
  const { data: users } = useSWR('/api/users', fetcher)
}

For immutable data:

import { useImmutableSWR } from '@/lib/swr'

function StaticContent() {
  const { data } = useImmutableSWR('/api/config', fetcher)
}

For mutations:

import { useSWRMutation } from 'swr/mutation'

function UpdateButton() {
  const { trigger } = useSWRMutation('/api/user', updateUser)
  return <button onClick={() => trigger()}>Update</button>
}

Reference: https://swr.vercel.app

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):

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):

// 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):

function updateElementStyles(element: HTMLElement) {
  element.style.cssText = `
    width: 100px;
    height: 200px;
    background-color: blue;
    border: 1px solid black;
  `
}

React example:

// Incorrect: changing styles one by one
function Box({ isHighlighted }: { isHighlighted: boolean }) {
  const ref = useRef<HTMLDivElement>(null)
  
  useEffect(() => {
    if (ref.current && isHighlighted) {
      ref.current.style.width = '100px'
      ref.current.style.height = '200px'
      ref.current.style.backgroundColor = 'blue'
    }
  }, [isHighlighted])
  
  return <div ref={ref}>Content</div>
}

// Correct: toggle class
function Box({ isHighlighted }: { isHighlighted: boolean }) {
  return (
    <div className={isHighlighted ? 'highlighted-box' : ''}>
      Content
    </div>
  )
}

Prefer CSS classes over inline styles when possible. Classes are cached by the browser and provide better separation of concerns.

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):

function ProjectList({ projects }: { projects: Project[] }) {
  return (
    <div>
      {projects.map(project => {
        // slugify() called 100+ times for same project names
        const slug = slugify(project.name)
        
        return <ProjectCard key={project.id} slug={slug} />
      })}
    </div>
  )
}

Correct (cached results):

// Module-level cache
const slugifyCache = new Map<string, string>()

function cachedSlugify(text: string): string {
  if (slugifyCache.has(text)) {
    return slugifyCache.get(text)!
  }
  const result = slugify(text)
  slugifyCache.set(text, result)
  return result
}

function ProjectList({ projects }: { projects: Project[] }) {
  return (
    <div>
      {projects.map(project => {
        // Computed only once per unique project name
        const slug = cachedSlugify(project.name)
        
        return <ProjectCard key={project.id} slug={slug} />
      })}
    </div>
  )
}

Simpler pattern for single-value functions:

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: How we made the Vercel Dashboard twice as fast

Cache Property Access in Loops

Cache object property lookups in hot paths.

Incorrect (3 lookups × N iterations):

for (let i = 0; i < arr.length; i++) {
  process(obj.config.settings.value)
}

Correct (1 lookup total):

const value = obj.config.settings.value
const len = arr.length
for (let i = 0; i < len; i++) {
  process(value)
}

Cache Storage API Calls

localStorage, sessionStorage, and document.cookie are synchronous and expensive. Cache reads in memory.

Incorrect (reads storage on every call):

function getTheme() {
  return localStorage.getItem('theme') ?? 'light'
}
// Called 10 times = 10 storage reads

Correct (Map cache):

const storageCache = new Map<string, string | null>()

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.

Cookie caching:

let cookieCache: Record<string, string> | null = null

function getCookie(name: string) {
  if (!cookieCache) {
    cookieCache = Object.fromEntries(
      document.cookie.split('; ').map(c => c.split('='))
    )
  }
  return cookieCache[name]
}

Important: If storage can change externally (another tab, server-set cookies), invalidate cache:

window.addEventListener('storage', (e) => {
  if (e.key) storageCache.delete(e.key)
})

document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'visible') {
    storageCache.clear()
  }
})

Combine Multiple Array Iterations

Multiple .filter() or .map() calls iterate the array multiple times. Combine into one loop.

Incorrect (3 iterations):

const admins = users.filter(u => u.isAdmin)
const testers = users.filter(u => u.isTester)
const inactive = users.filter(u => !u.isActive)

Correct (1 iteration):

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)
}

Early Return from Functions

Return early when result is determined to skip unnecessary processing.

Incorrect (processes all items even after finding answer):

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):

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

Hoist RegExp Creation

Don't create RegExp inside render. Hoist to module scope or memoize with useMemo().

Incorrect (new RegExp every render):

function Highlighter({ text, query }: Props) {
  const regex = new RegExp(`(${query})`, 'gi')
  const parts = text.split(regex)
  return <>{parts.map((part, i) => ...)}</>
}

Correct (memoize or hoist):

const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/

function Highlighter({ text, query }: Props) {
  const regex = useMemo(
    () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
    [query]
  )
  const parts = text.split(regex)
  return <>{parts.map((part, i) => ...)}</>
}

Warning: Global regex (/g) has mutable lastIndex state:

const regex = /foo/g
regex.test('foo')  // true, lastIndex = 3
regex.test('foo')  // false, lastIndex = 0

Build Index Maps for Repeated Lookups

Multiple .find() calls by the same key should use a Map.

Incorrect (O(n) per lookup):

function processOrders(orders: Order[], users: User[]) {
  return orders.map(order => ({
    ...order,
    user: users.find(u => u.id === order.userId)
  }))
}

Correct (O(1) per lookup):

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.

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):

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. There is also overhead of joining the arrays and comparing the strings.

Correct (O(1) length check first):

function hasChanges(current: string[], original: string[]) {
  // Early return if lengths differ
  if (current.length !== original.length) {
    return true
  }
  // Only sort/join 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 new approach is more efficient because:

• It avoids the overhead of sorting and joining the arrays when lengths differ
• It avoids consuming memory for the joined strings (especially important for large arrays)
• It avoids mutating the original arrays
• It returns early when a difference is found

Use Loop for Min/Max Instead of Sort

Finding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.

Incorrect (O(n log n) - sort to find latest):

interface Project {
  id: string
  name: string
  updatedAt: number
}

function getLatestProject(projects: Project[]) {
  const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
  return sorted[0]
}

Sorts the entire array just to find the maximum value.

Incorrect (O(n log n) - sort for oldest and newest):

function getOldestAndNewest(projects: Project[]) {
  const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)
  return { oldest: sorted[0], newest: sorted[sorted.length - 1] }
}

Still sorts unnecessarily when only min/max are needed.

Correct (O(n) - single loop):

function getLatestProject(projects: Project[]) {
  if (projects.length === 0) return null
  
  let latest = projects[0]
  
  for (let i = 1; i < projects.length; i++) {
    if (projects[i].updatedAt > 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 < oldest.updatedAt) oldest = projects[i]
    if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]
  }
  
  return { oldest, newest }
}

Single pass through the array, no copying, no sorting.

Alternative (Math.min/Math.max for small arrays):

const numbers = [5, 2, 8, 1, 9]
const min = Math.min(...numbers)
const max = Math.max(...numbers)

This works for small arrays but can be slower for very large arrays due to spread operator limitations. Use the loop approach for reliability.

Use Set/Map for O(1) Lookups

Convert arrays to Set/Map for repeated membership checks.

Incorrect (O(n) per check):

const allowedIds = ['a', 'b', 'c', ...]
items.filter(item => allowedIds.includes(item.id))

Correct (O(1) per check):

const allowedIds = new Set(['a', 'b', 'c', ...])
items.filter(item => allowedIds.has(item.id))

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):

function UserList({ users }: { users: User[] }) {
  // Mutates the users prop array!
  const sorted = useMemo(
    () => users.sort((a, b) => a.name.localeCompare(b.name)),
    [users]
  )
  return <div>{sorted.map(renderUser)}</div>
}

Correct (creates new array):

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 <div>{sorted.map(renderUser)}</div>
}

Why this matters in React:

1. Props/state mutations break React's immutability model - React expects props and state to be treated as read-only 2. Causes stale closure bugs - Mutating arrays inside closures (callbacks, effects) can lead to unexpected behavior

Browser support:

.toSorted() is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:

// Fallback for older browsers
const sorted = [...items].sort((a, b) => a.value - b.value)

Other immutable array methods:

• .toSorted() - immutable sort
• .toReversed() - immutable reverse
• .toSpliced() - immutable splice
• .with() - immutable element replacement

Use Activity Component for Show/Hide

Use React's <Activity> to preserve state/DOM for expensive components that frequently toggle visibility.

Usage:

import { Activity } from 'react'

function Dropdown({ isOpen }: Props) {
  return (
    <Activity mode={isOpen ? 'visible' : 'hidden'}>
      <ExpensiveMenu />
    </Activity>
  )
}

Avoids expensive re-renders and state loss.

Animate SVG Wrapper Instead of SVG Element

Many browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a <div> and animate the wrapper instead.

Incorrect (animating SVG directly - no hardware acceleration):

function LoadingSpinner() {
  return (
    <svg 
      className="animate-spin"
      width="24" 
      height="24" 
      viewBox="0 0 24 24"
    >
      <circle cx="12" cy="12" r="10" stroke="currentColor" />
    </svg>
  )
}

Correct (animating wrapper div - hardware accelerated):

function LoadingSpinner() {
  return (
    <div className="animate-spin">
      <svg 
        width="24" 
        height="24" 
        viewBox="0 0 24 24"
      >
        <circle cx="12" cy="12" r="10" stroke="currentColor" />
      </svg>
    </div>
  )
}

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.

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):

function Badge({ count }: { count: number }) {
  return (
    <div>
      {count && <span className="badge">{count}</span>}
    </div>
  )
}

// When count = 0, renders: <div>0</div>
// When count = 5, renders: <div><span class="badge">5</span></div>

Correct (renders nothing when count is 0):

function Badge({ count }: { count: number }) {
  return (
    <div>
      {count > 0 ? <span className="badge">{count}</span> : null}
    </div>
  )
}

// When count = 0, renders: <div></div>
// When count = 5, renders: <div><span class="badge">5</span></div>

CSS content-visibility for Long Lists

Apply content-visibility: auto to defer off-screen rendering.

CSS:

.message-item {
  content-visibility: auto;
  contain-intrinsic-size: 0 80px;
}

Example:

function MessageList({ messages }: { messages: Message[] }) {
  return (
    <div className="overflow-y-auto h-screen">
      {messages.map(msg => (
        <div key={msg.id} className="message-item">
          <Avatar user={msg.author} />
          <div>{msg.content}</div>
        </div>
      ))}
    </div>
  )
}

For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).

Hoist Static JSX Elements

Extract static JSX outside components to avoid re-creation.

Incorrect (recreates element every render):

function LoadingSkeleton() {
  return <div className="animate-pulse h-20 bg-gray-200" />
}

function Container() {
  return (
    <div>
      {loading && <LoadingSkeleton />}
    </div>
  )
}

Correct (reuses same element):

const loadingSkeleton = (
  <div className="animate-pulse h-20 bg-gray-200" />
)

function Container() {
  return (
    <div>
      {loading && loadingSkeleton}
    </div>
  )
}

This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.

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):

function ThemeWrapper({ children }: { children: ReactNode }) {
  // localStorage is not available on server - throws error
  const theme = localStorage.getItem('theme') || 'light'
  
  return (
    <div className={theme}>
      {children}
    </div>
  )
}

Server-side rendering will fail because localStorage is undefined.

Incorrect (visual flickering):

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 (
    <div className={theme}>
      {children}
    </div>
  )
}

Component first renders with default value (light), then updates after hydration, causing a visible flash of incorrect content.

Correct (no flicker, no hydration mismatch):

function ThemeWrapper({ children }: { children: ReactNode }) {
  return (
    <>
      <div id="theme-wrapper">
        {children}
      </div>
      <script
        dangerouslySetInnerHTML={{
          __html: `
            (function() {
              try {
                var theme = localStorage.getItem('theme') || 'light';
                var el = document.getElementById('theme-wrapper');
                if (el) el.className = theme;
              } catch (e) {}
            })();
          `,
        }}
      />
    </>
  )
}

The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.

This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.

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):

<path d="M 10.293847 20.847362 L 30.938472 40.192837" />

Correct (1 decimal place):

<path d="M 10.3 20.8 L 30.9 40.2" />

Automate with SVGO:

npx svgo --precision=1 --multipass icon.svg

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):

function ShareButton({ chatId }: { chatId: string }) {
  const searchParams = useSearchParams()

  const handleShare = () => {
    const ref = searchParams.get('ref')
    shareChat(chatId, { ref })
  }

  return <button onClick={handleShare}>Share</button>
}

Correct (reads on demand, no subscription):

function ShareButton({ chatId }: { chatId: string }) {
  const handleShare = () => {
    const params = new URLSearchParams(window.location.search)
    const ref = params.get('ref')
    shareChat(chatId, { ref })
  }

  return <button onClick={handleShare}>Share</button>
}

Narrow Effect Dependencies

Specify primitive dependencies instead of objects to minimize effect re-runs.

Incorrect (re-runs on any user field change):

useEffect(() => {
  console.log(user.id)
}, [user])

Correct (re-runs only when id changes):

useEffect(() => {
  console.log(user.id)
}, [user.id])

For derived state, compute outside effect:

// Incorrect: runs on width=767, 766, 765...
useEffect(() => {
  if (width < 768) {
    enableMobileMode()
  }
}, [width])

// Correct: runs only on boolean transition
const isMobile = width < 768
useEffect(() => {
  if (isMobile) {
    enableMobileMode()
  }
}, [isMobile])

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):

function Sidebar() {
  const width = useWindowWidth()  // updates continuously
  const isMobile = width < 768
  return <nav className={isMobile ? 'mobile' : 'desktop'}>
}

Correct (re-renders only when boolean changes):

function Sidebar() {
  const isMobile = useMediaQuery('(max-width: 767px)')
  return <nav className={isMobile ? 'mobile' : 'desktop'}>
}

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):

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 <SearchResults index={searchIndex} query={query} />
}

function UserProfile() {
  // JSON.parse runs on every render
  const [settings, setSettings] = useState(
    JSON.parse(localStorage.getItem('settings') || '{}')
  )
  
  return <SettingsForm settings={settings} onChange={setSettings} />
}

Correct (runs only once):

function FilteredList({ items }: { items: Item[] }) {
  // buildSearchIndex() runs ONLY on initial render
  const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items))
  const [query, setQuery] = useState('')
  
  return <SearchResults index={searchIndex} query={query} />
}

function UserProfile() {
  // JSON.parse runs only on initial render
  const [settings, setSettings] = useState(() => {
    const stored = localStorage.getItem('settings')
    return stored ? JSON.parse(stored) : {}
  })
  
  return <SettingsForm settings={settings} onChange={setSettings} />
}

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.

Extract to Memoized Components

Extract expensive work into memoized components to enable early returns before computation.

Incorrect (computes avatar even when loading):

function Profile({ user, loading }: Props) {
  const avatar = useMemo(() => {
    const id = computeAvatarId(user)
    return <Avatar id={id} />
  }, [user])

  if (loading) return <Skeleton />
  return <div>{avatar}</div>
}

Correct (skips computation when loading):

const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
  const id = useMemo(() => computeAvatarId(user), [user])
  return <Avatar id={id} />
})

function Profile({ user, loading }: Props) {
  if (loading) return <Skeleton />
  return (
    <div>
      <UserAvatar user={user} />
    </div>
  )
}

Use Transitions for Non-Urgent Updates

Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.

Incorrect (blocks UI on every scroll):

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):

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)
  }, [])
}

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:

import { LRUCache } from 'lru-cache'

const cache = new LRUCache<string, any>({
  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

Per-Request Deduplication with React.cache()

Use React.cache() for server-side request deduplication. Authentication and database queries benefit most.

Usage:

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.

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):

export default async function Page() {
  const header = await fetchHeader()
  return (
    <div>
      <div>{header}</div>
      <Sidebar />
    </div>
  )
}

async function Sidebar() {
  const items = await fetchSidebarItems()
  return <nav>{items.map(renderItem)}</nav>
}

Correct (both fetch simultaneously):

async function Header() {
  const data = await fetchHeader()
  return <div>{data}</div>
}

async function Sidebar() {
  const items = await fetchSidebarItems()
  return <nav>{items.map(renderItem)}</nav>
}

export default function Page() {
  return (
    <div>
      <Header />
      <Sidebar />
    </div>
  )
}

Alternative with children prop:

async function Layout({ children }: { children: ReactNode }) {
  const header = await fetchHeader()
  return (
    <div>
      <div>{header}</div>
      {children}
    </div>
  )
}

async function Sidebar() {
  const items = await fetchSidebarItems()
  return <nav>{items.map(renderItem)}</nav>
}

export default function Page() {
  return (
    <Layout>
      <Sidebar />
    </Layout>
  )
}

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):

async function Page() {
  const user = await fetchUser()  // 50 fields
  return <Profile user={user} />
}

'use client'
function Profile({ user }: { user: User }) {
  return <div>{user.name}</div>  // uses 1 field
}

Correct (serializes only 1 field):

async function Page() {
  const user = await fetchUser()
  return <Profile name={user.name} />
}

'use client'
function Profile({ name }: { name: string }) {
  return <div>{name}</div>
}