vercel-react-best-practices

Original：🇺🇸 English

Not Translated

React and Next.js performance optimization guidelines from Vercel Engineering. Use when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.

7.8kinstalls

Sourcesupercent-io/skills-template

Added on2026-02-13

NPX Install

npx skill4agent add supercent-io/skills-template vercel-react-best-practices

SKILL.md Content

Vercel React Best Practices

Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 45 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

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


async-
bundle-
server-
client-
rerender-
rendering-
js-
advanced-

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

How to Use

For detailed explanations and code examples, read the full compiled document:

AGENTS.md

Each rule contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Additional context and references

Key Examples

Promise.all for Independent Operations (CRITICAL)

typescript

// ❌ Sequential: 3 round trips
const user = await fetchUser()
const posts = await fetchPosts()
const comments = await fetchComments()

// ✅ Parallel: 1 round trip
const [user, posts, comments] = await Promise.all([
  fetchUser(),
  fetchPosts(),
  fetchComments()
])

Avoid Barrel File Imports (CRITICAL)

tsx

// ❌ Imports entire library (200-800ms import cost)
import { Check, X, Menu } from 'lucide-react'

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

Dynamic Imports for Heavy Components (CRITICAL)

tsx

// ❌ Monaco bundles with main chunk ~300KB
import { MonacoEditor } from './monaco-editor'

// ✅ Monaco loads on demand
import dynamic from 'next/dynamic'
const MonacoEditor = dynamic(
  () => import('./monaco-editor').then(m => m.MonacoEditor),
  { ssr: false }
)

Use Functional setState (MEDIUM)

tsx

// ❌ Requires state as dependency, stale closure risk
const addItems = useCallback((newItems) => {
  setItems([...items, ...newItems])
}, [items])

// ✅ Stable callback, no stale closures
const addItems = useCallback((newItems) => {
  setItems(curr => [...curr, ...newItems])
}, [])