Vercel React Best Practices
Give your agent a prioritized React and Next.js performance rulebook while you generate, refactor, or review UI code.
Overview
Vercel React Best Practices is an agent skill most often used in Build (also Ship perf) that applies 40+ prioritized React and Next.js performance rules for AI-assisted refactors and codegen.
Install
npx skills add https://github.com/vercel-labs/sandcastle --skill vercel-react-best-practicesWhat is this skill?
- 40+ rules across 8 categories prioritized from critical waterfalls and bundle size to advanced patterns
- Each rule pairs incorrect vs correct examples with impact framing for agent-driven refactors
- Covers eliminating async waterfalls, bundle optimization, and strategic Suspense boundaries
- Written for AI-assisted workflows (Vercel Engineering, Version 1.0.0, January 2026)
- Version 1.0.0 (January 2026)
Adoption & trust: 4 installs on skills.sh; 48 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your agent keeps producing React or Next.js code with serial data fetching, fat bundles, and patterns that look fine but fail under real traffic.
Who is it for?
Solo builders on Next.js who want agents to follow one consistent, Vercel-authored performance standard across generates and refactors.
Skip if: Non-React stacks, greenfield product discovery with no UI yet, or backend-only API work with no Next.js surface.
When should I use this skill?
Maintaining, generating, or refactoring React and Next.js codebases with an AI agent that should follow consistent performance rules.
What do I get? / Deliverables
Generated and refactored UI code aligns with impact-ordered rules—fewer waterfalls, smaller bundles, and clearer Suspense boundaries—before you ship.
- Refactored components and routes aligned to prioritized rules
- Documented incorrect-to-correct pattern changes in code
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Most invocations happen while building or changing React surfaces, which is the primary frontend shelf even though many rules target ship-time performance. Frontend is where React/Next.js components and routes live; the guide is optimized for automated maintenance and codegen in that layer.
Where it fits
Agent generates a new dashboard page and parallelizes independent fetches per the Promise.all and waterfall rules.
You refactor barrel imports in a component library to shrink the client bundle before feature freeze.
Pre-release pass applies critical-tier rules to API routes that still chain awaits sequentially.
Automated review cites incorrect vs correct examples when flagging Suspense boundary mistakes.
How it compares
A rule-backed review guide for React/Next—not a generic linter config or a deployment skill.
Common Questions / FAQ
Who is vercel-react-best-practices for?
Solo and indie developers using AI agents to maintain, generate, or refactor React and Next.js apps who want Vercel’s prioritized performance conventions.
When should I use vercel-react-best-practices?
In Build (frontend) while implementing or refactoring UI; in Ship (perf) before release when tuning waterfalls, bundles, and Suspense; and during automated code review passes on Next.js repos.
Is vercel-react-best-practices safe to install?
It is documentation-style guidance; confirm trust via the Security Audits panel on this page and ensure your agent only changes code you intend to review.
SKILL.md
READMESKILL.md - Vercel React Best Practices
# React Best Practices **Version 1.0.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. Humans > may also find it useful, but guidance here is optimized for automation > and consistency by AI-assisted workflows. --- ## 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](#1-eliminating-waterfalls) — **CRITICAL** - 1.1 [Defer Await Until Needed](#11-defer-await-until-needed) - 1.2 [Dependency-Based Parallelization](#12-dependency-based-parallelization) - 1.3 [Prevent Waterfall Chains in API Routes](#13-prevent-waterfall-chains-in-api-routes) - 1.4 [Promise.all() for Independent Operations](#14-promiseall-for-independent-operations) - 1.5 [Strategic Suspense Boundaries](#15-strategic-suspense-boundaries) 2. [Bundle Size Optimization](#2-bundle-size-optimization) — **CRITICAL** - 2.1 [Avoid Barrel File Imports](#21-avoid-barrel-file-imports) - 2.2 [Conditional Module Loading](#22-conditional-module-loading) - 2.3 [Defer Non-Critical Third-Party Libraries](#23-defer-non-critical-third-party-libraries) - 2.4 [Dynamic Imports for Heavy Components](#24-dynamic-imports-for-heavy-components) - 2.5 [Preload Based on User Intent](#25-preload-based-on-user-intent) 3. [Server-Side Performance](#3-server-side-performance) — **HIGH** - 3.1 [Authenticate Server Actions Like API Routes](#31-authenticate-server-actions-like-api-routes) - 3.2 [Avoid Duplicate Serialization in RSC Props](#32-avoid-duplicate-serialization-in-rsc-props) - 3.3 [Cross-Request LRU Caching](#33-cross-request-lru-caching) - 3.4 [Minimize Serialization at RSC Boundaries](#34-minimize-serialization-at-rsc-boundaries) - 3.5 [Parallel Data Fetching with Component Composition](#35-parallel-data-fetching-with-component-composition) - 3.6 [Per-Request Deduplication with React.cache()](#36-per-request-deduplication-with-reactcache) - 3.7 [Use after() for Non-Blocking Operations](#37-use-after-for-non-blocking-operations) 4. [Client-Side Data Fetching](#4-client-side-data-fetching) — **MEDIUM-HIGH** - 4.1 [Deduplicate Global Event Listeners](#41-deduplicate-global-event-listeners) - 4.2 [Use Passive Event Listeners for Scrolling Performance](#42-use-passive-event-listeners-for-scrolling-performance) - 4.3 [Use SWR for Automatic Deduplication](#43-use-swr-for-automatic-deduplication) - 4.4 [Version and Minimize localStorage Data](#44-version-and-minimize-localstorage-data) 5. [Re-render Optimization](#5-re-render-optimization) — **MEDIUM** - 5.1 [Calculate Derived State During Rendering](#51-calculate-derived-state-during-rendering) - 5.2 [Defer State Reads to Usage Point](#52-defer-state-reads-to-usage-point) - 5.3 [Do not wrap a simple expression with a primitive result type in useMemo](#53-do-not-wrap-a-simple-expression-with-a-primitive-result-type-in-usememo) - 5.4 [Extract Default Non-primitive Parameter Value from Memoized Component to Constant](#54-extract-default-non-primitive-parameter-value-from-memoized-component-to-constant) - 5.5 [Extract to Memoized Components](#55-extract-to-memoized-components) - 5.6 [Narrow Effect Dependencies](#56-narrow-effect-dependencies) - 5.7 [Put Interaction Logic in Event Handlers](#57-put-interaction-logic-in-event-handlers) - 5.8 [Subscribe to Derived State](#58-subscribe-to-derived-state) - 5.9 [Use Functional setState Updates](#59-use-