vercel-react-best-practices

45 performance optimization rules for React and Next.js, organized by impact and category. Covers 8 rule categories from eliminating waterfalls and bundle optimization (critical) through JavaScript performance and advanced patterns (low priority) Each rule includes explanation, before/after code examples, and context to guide automated refactoring and code generation Prioritized by impact: waterfalls and bundle size are critical; server-side performance and re-render optimization are high/medium priority Designed for use when writing components, implementing data fetching, reviewing code, or optimizing performance in React/Next.js applications

INSTALLATION

npx skills add https://github.com/am-will/codex-skills --skill vercel-react-best-practices

Run in your project or agent environment. Adjust flags if your CLI version differs.

SKILL.md

Vercel React Best Practices

Name: vercel-react-best-practices
Author: am-will

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

Priority

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

Read individual rule files for detailed explanations and code examples:

rules/async-parallel.md

rules/bundle-barrel-imports.md

rules/_sections.md

Each rule file contains:

Brief explanation of why it matters

Incorrect code example with explanation

Correct code example with explanation

Additional context and references

Full Compiled Document

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