React Best Practices

React and Next.js performance optimization guidelines from Vercel Engineering. 57 rules across 8 categories for writing, reviewing, and refactoring React code.

Security Scan

The skill is an instruction-only collection of React/Next.js performance rules and is internally consistent with its stated purpose; it requests no credentials, no installs, and contains no code that contradicts the description — though the repository provenance is unknown so you may want to vet it before allowing automated code changes.

Purpose & Capability

Name/description match the provided content: a ruleset for React and Next.js performance. Files (README, SKILL.md, AGENTS.md and many rule markdowns) all align with the stated goal. There are no unrelated environment variables, binaries, or config paths requested.

Instruction Scope

SKILL.md + AGENTS.md are guidance documents for humans and for agents to use when writing/refactoring code. They do not request secrets or system files. Note: AGENTS.md explicitly targets automation/LLMs and is intended for agents to perform maintenance/refactors; that is coherent with the skill purpose but means an agent using this skill could modify your codebase if allowed—review any automated changes before applying.

Install Mechanism

No install spec in the registry (instruction-only). SKILL.md and README show example install commands (npx clawhub, copy into local skill dirs) but the skill package itself includes no install script or extracted binaries. Low install risk.

Credentials

The skill declares no required environment variables, credentials, or config paths. The guidance mentions common libraries (better-all, lru-cache, @vercel/analytics) but does not request tokens or secrets; the requested capabilities are proportionate to the stated purpose.

Persistence & Privilege

always:false and disable-model-invocation:false (normal). The skill does not request persistent presence, nor does it modify other skills or system-wide settings. Autonomous agent invocation is allowed by default but is not a unique privilege of this skill.

Assessment

This appears to be a coherent, instruction-only guide for improving React/Next.js performance and does not request credentials or install arbitrary code. Before you enable an agent to act autonomously with this skill, consider: (1) provenance — the registry metadata lists no homepage and source is unknown, so verify the origin if you require an official Vercel document; (2) automation risk — AGENTS.md is written for LLMs and enables automated refactors, so require human review or use a dry-run mode when letting an agent change your code; (3) dependency recommendations — some rules suggest libraries (better-all, lru-cache, @vercel/analytics); add third-party libs deliberately and review licenses; (4) validate any suggested code changes in CI and tests. If you only want read-only guidance, this skill is low-risk; if you plan to let an agent automatically modify code, apply normal code-review safeguards.

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

Installation

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install react-best-practices

WHAT This Skill Does

Provides actionable rules for:

• Eliminating request waterfalls
• Optimizing bundle size
• Improving server-side performance
• Efficient client-side data fetching
• Minimizing re-renders
• Rendering performance optimizations
• JavaScript micro-optimizations
• Advanced patterns for edge cases

WHEN To Use

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

KEYWORDS

react performance, nextjs optimization, bundle size, waterfalls, suspense, server components, rsc, rerender, usememo, dynamic import, parallel fetching, cache, swr

Rule Categories by Priority

Priority	Category	Impact	Rule 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)

Rule	Description
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)

Rule	Description
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)

Rule	Description
server-auth-actions	Authenticate server actions like API routes
server-cache-react	Use React.cache() for per-request dedup
server-cache-lru	Use LRU cache for cross-request caching
server-dedup-props	Avoid duplicate serialization in RSC props
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)

Rule	Description
client-swr-dedup	Use SWR for automatic request deduplication
client-event-listeners	Deduplicate global event listeners
client-passive-event-listeners	Use passive listeners for scroll
client-localstorage-schema	Version and minimize localStorage data

5. Re-render Optimization (MEDIUM)

Rule	Description
rerender-defer-reads	Don't subscribe to state only used in callbacks
rerender-memo	Extract expensive work into memoized components
rerender-memo-with-default-value	Hoist default non-primitive props
rerender-dependencies	Use primitive dependencies in effects
rerender-derived-state	Subscribe to derived booleans, not raw values
rerender-derived-state-no-effect	Derive state during render, not effects
rerender-functional-setstate	Use functional setState for stable callbacks
rerender-lazy-state-init	Pass function to useState for expensive values
rerender-simple-expression-in-memo	Avoid memo for simple primitives
rerender-move-effect-to-event	Put interaction logic in event handlers
rerender-transitions	Use startTransition for non-urgent updates
rerender-use-ref-transient-values	Use refs for transient frequent values

6. Rendering Performance (MEDIUM)

Rule	Description
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-hydration-suppress-warning	Suppress expected mismatches
rendering-activity	Use Activity component for show/hide
rendering-conditional-render	Use ternary, not && for conditionals
rendering-usetransition-loading	Prefer useTransition for loading state

7. JavaScript Performance (LOW-MEDIUM)

Rule	Description
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 ops
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)

Rule	Description
advanced-event-handler-refs	Store event handlers in refs
advanced-init-once	Initialize app once per app load
advanced-use-latest	useLatest for stable callback refs

How to Use

Reading Individual Rules

Each rule file in rules/ contains:

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

rules/async-parallel.md
rules/bundle-barrel-imports.md
rules/rerender-memo.md

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

This 2900+ line document contains every rule with full code examples and detailed explanations, suitable for comprehensive reference.

Key Patterns

Parallel Data Fetching

// Bad: sequential
const user = await fetchUser()
const posts = await fetchPosts()

// Good: parallel
const [user, posts] = await Promise.all([
  fetchUser(),
  fetchPosts()
])

Dynamic Imports

// Bad: bundles Monaco with main chunk
import { MonacoEditor } from './monaco-editor'

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

Functional setState

// Bad: stale closure risk
const addItem = useCallback((item) => {
  setItems([...items, item])
}, [items]) // recreates on every items change

// Good: always uses latest state
const addItem = useCallback((item) => {
  setItems(curr => [...curr, item])
}, []) // stable reference

NEVER Do

1. NEVER await operations sequentially when they can run in parallel
2. NEVER import from barrel files (import { X } from 'lib') — import directly
3. NEVER skip authentication in Server Actions — treat them like API routes
4. NEVER pass entire objects to client components when only one field is needed
5. NEVER use && for conditional rendering with numbers — use ternary
6. NEVER subscribe to state only used in event handlers — read on demand
7. NEVER mutate arrays with .sort() — use .toSorted()
8. NEVER put initialization in useEffect([]) — use module-level guard