React Best Practices
Give your coding agent a prioritized rulebook for React and Next.js refactors so waterfalls and bundle bloat get fixed consistently.
Overview
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 automated refactors and code generation.
Install
npx skills add https://github.com/vercel-labs/vercel-plugin --skill react-best-practicesWhat is this skill?
- 40+ performance rules across 8 impact-ordered categories from waterfall elimination to advanced patterns
- Critical-tier guidance on deferring await, Promise.all parallelization, and API-route waterfall prevention
- Bundle-size rules including avoiding barrel imports and other Next.js-specific trimming tactics
- Each rule pairs incorrect vs correct examples with stated impact metrics for agent-driven refactors
- Optimized for AI maintenance, generation, and refactors—not a human-only style guide
- 40+ rules across 8 categories
- Version 1.0.0 (January 2026)
- Rules prioritized from critical (waterfalls, bundle size) to incremental patterns
Adoption & trust: 819 installs on skills.sh; 186 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You ship React or Next.js features with agents but every session invents different async, import, and Suspense patterns that silently hurt load time and waterfalls.
Who is it for?
Solo builders maintaining or generating Next.js/React apps who want agent edits aligned with production-grade performance priorities.
Skip if: Teams that only need visual design tokens, non-React stacks, or backend-only APIs with no client bundle concerns.
When should I use this skill?
Maintaining, generating, or refactoring React and Next.js codebases with AI-assisted workflows when performance and consistency matter.
What do I get? / Deliverables
Your agent refactors and new UI code follow Vercel’s impact-ordered rules so waterfalls shrink, bundles stay lean, and performance fixes are repeatable across the repo.
- Refactored components and routes aligned to rule categories
- Documented incorrect-vs-correct pattern fixes in PRs
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Build because the skill governs how React/Next UI code is written and refactored during product construction. Frontend is the right subphase: rules target components, imports, Suspense, and client/server boundaries rather than infra or distribution.
Where it fits
Refactor a dashboard page so independent fetches run via Promise.all instead of sequential awaits.
Replace barrel imports in a marketing site to cut client JavaScript before launch.
Audit agent-generated API routes for waterfall chains before production deploy.
Score a PR against the eight category priorities before merging a Next.js feature.
How it compares
Use instead of ad-hoc “make it faster” chat prompts that lack prioritized, example-backed React/Next.js rules.
Common Questions / FAQ
Who is react-best-practices for?
Indie and solo developers shipping React or Next.js products with AI coding agents who need consistent, high-impact performance guardrails during refactors and codegen.
When should I use react-best-practices?
During Build frontend work when generating or refactoring components and routes; before Ship when tuning perf, bundle size, and data-fetch waterfalls; and when reviewing agent-produced Next.js PRs for regression patterns.
Is react-best-practices safe to install?
It is documentation-style procedural knowledge with no runtime hooks; review the Security Audits panel on this Prism page before trusting any third-party skill package in your agent.
SKILL.md
READMESKILL.md - 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 [Hoist Static I/O to Module Level](#34-hoist-static-io-to-module-level) - 3.5 [Minimize Serialization at RSC Boundaries](#35-minimize-serialization-at-rsc-boundaries) - 3.6 [Parallel Data Fetching with Component Composition](#36-parallel-data-fetching-with-component-composition) - 3.7 [Per-Request Deduplication with React.cache()](#37-per-request-deduplication-with-reactcache) - 3.8 [Use after() for Non-Blocking Operations](#38-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 [Don't Define Components Inside Components](#54-dont-define-components-inside-components) - 5.5 [Extract Default Non-primitive Parameter Value from Memoized Component to Constant](#55-extract-default-non-primitive-parameter-value-from-memoized-component-to-constant) - 5.6 [Extract to Memoized Components](#56-extract-to-memoized-components) - 5.7 [Narrow Effect Dependencies](#57-narrow-effect-dependencies) - 5.8 [Put Interaction Logic in Ev