alfredolopez80/vercel-react-best-practices

Vercel React Best Practices

v2.88 Key Changes (MODEL-AGNOSTIC)

• Model-agnostic: Uses model configured in ~/.claude/settings.json or CLI/env vars
• No flags required: Works with the configured default model
• Flexible: Works with GLM-5, Claude, Minimax, or any configured model
• Settings-driven: Model selection via ANTHROPIC_DEFAULT_*_MODEL env vars

Comprehensive performance optimization guide for React and Next.js applications from Vercel Engineering. Contains 45 rules across 8 categories, prioritized by impact.

When to Apply

Reference these guidelines when:

• Writing new React components or Next.js pages
• Implementing data fetching (client or server-side)
• Reviewing code for performance issues
• Refactoring existing React/Next.js code
• Optimizing bundle size or load times

Rule Categories by Priority

| Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Eliminating Waterfalls | CRITICAL | async- | | 2 | Bundle Size Optimization | CRITICAL | bundle- | | 3 | Server-Side Performance | HIGH | server- | | 4 | Client-Side Data Fetching | MEDIUM-HIGH | client- | | 5 | Re-render Optimization | MEDIUM | rerender- | | 6 | Rendering Performance | MEDIUM | rendering- | | 7 | JavaScript Performance | LOW-MEDIUM | js- | | 8 | Advanced Patterns | LOW | advanced- |

Quick Reference

1. Eliminating Waterfalls (CRITICAL)

• async-defer-await - Move await into branches where actually used
• async-parallel - Use Promise.all() for independent operations
• async-dependencies - Use better-all for partial dependencies
• async-api-routes - Start promises early, await late in API routes
• async-suspense-boundaries - Use Suspense to stream content

2. Bundle Size Optimization (CRITICAL)

• bundle-barrel-imports - Import directly, avoid barrel files
• bundle-dynamic-imports - Use next/dynamic for heavy components
• bundle-defer-third-party - Load analytics/logging after hydration
• bundle-conditional - Load modules only when feature is activated
• bundle-preload - Preload on hover/focus for perceived speed

3. Server-Side Performance (HIGH)

• server-cache-react - Use React.cache() for per-request deduplication
• server-cache-lru - Use LRU cache for cross-request caching
• server-serialization - Minimize data passed to client components
• server-parallel-fetching - Restructure components to parallelize fetches
• server-after-nonblocking - Use after() for non-blocking operations

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

• client-swr-dedup - Use SWR for automatic request deduplication
• client-event-listeners - Deduplicate global event listeners

5. Re-render Optimization (MEDIUM)

• rerender-defer-reads - Don't subscribe to state only used in callbacks
• rerender-memo - Extract expensive work into memoized components
• rerender-dependencies - Use primitive dependencies in effects
• rerender-derived-state - Subscribe to derived booleans, not raw values
• rerender-functional-setstate - Use functional setState for stable callbacks
• rerender-lazy-state-init - Pass function to useState for expensive values
• rerender-transitions - Use startTransition for non-urgent updates

6. Rendering Performance (MEDIUM)

• rendering-animate-svg-wrapper - Animate div wrapper, not SVG element
• rendering-content-visibility - Use content-visibility for long lists
• rendering-hoist-jsx - Extract static JSX outside components
• rendering-svg-precision - Reduce SVG coordinate precision
• rendering-hydration-no-flicker - Use inline script for client-only data
• rendering-activity - Use Activity component for show/hide
• rendering-conditional-render - Use ternary, not && for conditionals

7. JavaScript Performance (LOW-MEDIUM)

• js-batch-dom-css - Group CSS changes via classes or cssText
• js-index-maps - Build Map for repeated lookups
• js-cache-property-access - Cache object properties in loops
• js-cache-function-results - Cache function results in module-level Map
• js-cache-storage - Cache localStorage/sessionStorage reads
• js-combine-iterations - Combine multiple filter/map into one loop
• js-length-check-first - Check array length before expensive comparison
• js-early-exit - Return early from functions
• js-hoist-regexp - Hoist RegExp creation outside loops
• js-min-max-loop - Use loop for min/max instead of sort
• js-set-map-lookups - Use Set/Map for O(1) lookups
• js-tosorted-immutable - Use toSorted() for immutability

8. Advanced Patterns (LOW)

• advanced-event-handler-refs - Store event handlers in refs
• advanced-use-latest - useLatest for stable callback refs

Key Performance Rules

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

  return processUserData(userData)
}

Correct: only blocks when needed

async function handleRequest(userId: string, skipProcessing: boolean) {
  if (skipProcessing) {
    // Returns immediately without waiting
    return { skipped: true }
  }

  const userData = await fetchUserData(userId)
  return processUserData(userData)
}

1.2 Dependency-Based Parallelization

For operations with partial dependencies, use better-all to maximize parallelism.

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

2.1 Avoid Barrel File Imports

Import directly from modules instead of barrel files to enable better tree-shaking.

Incorrect: barrel file imports

import { Button, Input, Card, Modal } from '@/components'

Correct: direct imports

import Button from '@/components/Button'
import Input from '@/components/Input'
import Card from '@/components/Card'
import Modal from '@/components/Modal'

2.4 Dynamic Imports for Heavy Components

Use next/dynamic for heavy components that aren't needed on initial render.

import dynamic from 'next/dynamic'

const HeavyChart = dynamic(() => import('@/components/HeavyChart'), {
  loading: () => <p>Loading...</p>,
  ssr: false  // Disable if no SSR needed
})

3.6 Per-Request Deduplication with React.cache()

Use React.cache() to deduplicate calls within the same request.

import { cache } from 'react'

const getUser = cache(async (id: string) => {
  return db.user.findUnique({ where: { id } })
})

// Both calls return the same promise within the same request
const user1 = await getUser('123')
const user2 = await getUser('123')  // No additional database query

4.3 Use SWR for Automatic Deduplication

Use SWR for automatic request deduplication and caching.

import useSWR from 'swr'

function useUser(id: string) {
  return useSWR(`/api/user/${id}`, fetcher)
}

5.2 Extract to Memoized Components

Extract expensive work into memoized components to prevent unnecessary re-renders.

// Before: Expensive calculation on every render
function Dashboard({ data }) {
  const summary = computeSummary(data)  // Runs every render

  return <div>{summary}</div>
}

// After: Memoized component
const Summary = memo(({ data }) => {
  return <div>{computeSummary(data)}</div>
})

function Dashboard({ data }) {
  return <Summary data={data} />
}

5.7 Use Transitions for Non-Urgent Updates

Use startTransition for non-urgent updates to keep the UI responsive.

import { useState, startTransition } from 'react'

function SearchResults({ query }) {
  const [results, setResults] = useState([])

  function handleChange(e) {
    startTransition(() => {
      setResults(search(e.target.value))
    })
  }

  return <input onChange={handleChange} />
}

---

Version: 1.0.0 Author: Vercel Engineering License: MIT Reference: https://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices