Vercel React Best Practices
Give your coding agent Vercel-style React and Next.js performance rules so refactors kill waterfalls and shrink bundles instead of guessing.
Overview
Vercel React Best Practices is an agent skill most often used in Build (also Ship) that applies 40+ Vercel Engineering performance rules for React and Next.js refactors and codegen.
Install
npx skills add https://github.com/am-will/codex-skills --skill vercel-react-best-practicesWhat is this skill?
- 40+ prioritized rules across 8 impact-ordered categories from CRITICAL bundle and waterfall fixes to advanced patterns
- Waterfall elimination: defer await, Promise.all, API-route parallelization, strategic Suspense boundaries
- Bundle guidance including avoiding barrel imports and other size-critical anti-patterns
- Each rule pairs incorrect vs correct examples with stated impact for agent-driven refactors
- Version 0.1.0 (January 2026) framed explicitly for AI agents maintaining Vercel-grade React codebases
- 40+ rules across 8 categories
- Rules prioritized from CRITICAL (waterfalls, bundle size) to incremental advanced patterns
- Document version 0.1.0 (January 2026)
Adoption & trust: 1.2k installs on skills.sh; 941 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your Next.js app passes tests but still ships sequential data waterfalls and fat client bundles that agents keep reintroducing.
Who is it for?
Solo builders on React 19 / Next.js who want agent refactors aligned with Vercel performance priorities before users feel latency.
Skip if: Non-React stacks, design-only work, or teams that only need accessibility or security review without performance structure.
When should I use this skill?
Maintaining, generating, or refactoring React and Next.js codebases where performance, waterfalls, or bundle size are concerns.
What do I get? / Deliverables
Generated and refactored React/Next code follows impact-prioritized rules so independent work parallelizes and bundle-critical import patterns disappear.
- Refactored components and routes following prioritized rules
- Reduced waterfall fetch patterns
- Bundle-oriented import and code-splitting fixes
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
The skill is a codegen and refactor playbook for React/Next UI work, so Build is where it first lands on the journey shelf. Frontend is the canonical home for component architecture, data fetching patterns, Suspense, and bundle rules aimed at app surfaces.
Where it fits
Scaffold a dashboard page so independent queries run under Promise.all instead of await chains.
Shape API route handlers to avoid waterfall middleware before calling upstream services.
Pre-launch pass to swap barrel imports and tighten Suspense boundaries on critical paths.
Targeted refactor after p95 spikes tied to sequential server fetches in a hot route.
How it compares
Use as a rule-backed skill package, not an MCP server—procedural Next/React performance law the agent applies while editing files.
Common Questions / FAQ
Who is vercel-react-best-practices for?
Indie full-stack and frontend-heavy builders using React and Next.js with Claude Code, Codex, or Cursor who want consistent performance guardrails during AI-assisted edits.
When should I use vercel-react-best-practices?
Use it while building UI and data layers in Build frontend, during Ship perf hardening before launch, and when Operate slowdowns point to fetch waterfalls or bundle regressions in production code.
Is vercel-react-best-practices safe to install?
It is documentation and rules for local codegen—no external audit service; confirm repo access expectations on the Security Audits panel for this Prism listing.
SKILL.md
READMESKILL.md - Vercel React Best Practices
# React Best Practices **Version 0.1.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 at Vercel. 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 [Cross-Request LRU Caching](#31-cross-request-lru-caching) - 3.2 [Minimize Serialization at RSC Boundaries](#32-minimize-serialization-at-rsc-boundaries) - 3.3 [Parallel Data Fetching with Component Composition](#33-parallel-data-fetching-with-component-composition) - 3.4 [Per-Request Deduplication with React.cache()](#34-per-request-deduplication-with-reactcache) - 3.5 [Use after() for Non-Blocking Operations](#35-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 SWR for Automatic Deduplication](#42-use-swr-for-automatic-deduplication) 5. [Re-render Optimization](#5-re-render-optimization) — **MEDIUM** - 5.1 [Defer State Reads to Usage Point](#51-defer-state-reads-to-usage-point) - 5.2 [Extract to Memoized Components](#52-extract-to-memoized-components) - 5.3 [Narrow Effect Dependencies](#53-narrow-effect-dependencies) - 5.4 [Subscribe to Derived State](#54-subscribe-to-derived-state) - 5.5 [Use Functional setState Updates](#55-use-functional-setstate-updates) - 5.6 [Use Lazy State Initialization](#56-use-lazy-state-initialization) - 5.7 [Use Transitions for Non-Urgent Updates](#57-use-transitions-for-non-urgent-updates) 6. [Rendering Performance](#6-rendering-performance) — **MEDIUM** - 6.1 [Animate SVG Wrapper Instead of SVG Element](#61-animate-svg-wrapper-instead-of-svg-element) - 6.2 [CSS content-visibility for Long Lists](#62-css-content-visibility-for-long-lists) - 6.3 [Hoist Static JSX Elements](#63-hoist-static-jsx-elements) - 6.4 [Optimize SVG Precision](#64-optimize-svg-precision) - 6.5 [Prevent Hydration Mismatch Without Flickering](#65-prevent-hydration-mismatch-without-flickering) - 6.6 [Use Activity Component for Show/Hide](#66-use-activity-component-for-showhide) - 6.7 [Use Explicit Conditional Rendering](#67-use-explicit-conditional-rendering) 7. [JavaScript Performance](#7-javascript-performance) — **LOW-MEDIUM** -