Skip to main content

​
Overview

The Vercel React Best Practices agent skill provides comprehensive performance optimization guidelines for React and Next.js applications. This skill contains 57 rules across 8 categories, prioritized by impact from critical (eliminating waterfalls, reducing bundle size) to incremental improvements.
Production Origin: These patterns are maintained by Vercel Engineering and are battle-tested in production environments.

​
What This Skill Does

The skill guides AI agents to write, review, and refactor React/Next.js code following performance best practices:
  • Eliminates Waterfalls - Parallelize async operations, defer awaits, use Suspense boundaries
  • Optimizes Bundle Size - Direct imports, dynamic imports, code splitting
  • Improves Server-Side Performance - React.cache(), LRU caching, minimal serialization
  • Enhances Client-Side Fetching - SWR deduplication, event listener optimization
  • Reduces Re-renders - Memoization, derived state, transitions
  • Boosts Rendering Performance - Content visibility, SVG optimization, hydration fixes
  • Optimizes JavaScript - Loop improvements, Set/Map usage, early returns
  • Advanced Patterns - useEffectEvent, stable callbacks, app initialization

​
Location in TailStack Packages

The Vercel React Best Practices skill is available in multiple packages across the monorepo:

​
React Package

# Agent skill files
packages/react/.agent/skills/vercel-react-best-practices/
packages/react/.claude/skills/vercel-react-best-practices/
packages/react/.cursor/skills/vercel-react-best-practices/
packages/react/.opencode/skills/vercel-react-best-practices/

​
Core Package

# Shared across the monorepo
packages/core/.agent/skills/vercel-react-best-practices/
packages/core/.claude/skills/vercel-react-best-practices/
packages/core/.cursor/skills/vercel-react-best-practices/
packages/core/.opencode/skills/vercel-react-best-practices/

​
Skill Structure

Skill Contents

Each skill directory contains:
  • SKILL.md - Skill metadata and quick reference guide
  • AGENTS.md - Full compiled documentation with all rules
  • rules/ - Individual rule files (57 total) organized by category:
    • async-*.md - Eliminating waterfalls (5 rules)
    • bundle-*.md - Bundle size optimization (5 rules)
    • server-*.md - Server-side performance (7 rules)
    • client-*.md - Client-side data fetching (4 rules)
    • rerender-*.md - Re-render optimization (12 rules)
    • rendering-*.md - Rendering performance (9 rules)
    • js-*.md - JavaScript performance (12 rules)
    • advanced-*.md - Advanced patterns (3 rules)

​
Using with AI Agents

​
Claude Desktop & Claude.ai

1

Locate Skill Files

Navigate to packages/react/.claude/skills/vercel-react-best-practices/
2

Reference in Conversations

Claude automatically loads skills from the .claude/ directory when working in the project.
3

Ask for Optimization

Example: “Review this component and apply Vercel React best practices”

​
Cursor

1

Locate Skill Files

Skills are in packages/react/.cursor/skills/vercel-react-best-practices/
2

Use in Rules

Add to .cursorrules file:
When writing React code, follow patterns from .cursor/skills/vercel-react-best-practices/
3

Reference Specific Rules

Example: “Apply the async-parallel pattern from vercel-react-best-practices”

​
OpenCode

1

Load the Skill

Skills in packages/react/.opencode/skills/vercel-react-best-practices/ are automatically available
2

Request Optimizations

Example: “Refactor this data fetching to eliminate waterfalls using Vercel best practices”

​
Generic AI Agents

1

Read AGENTS.md

The complete guide is in packages/react/.agent/skills/vercel-react-best-practices/AGENTS.md
2

Include in Context

Provide the AGENTS.md file or specific rule files as context to your AI agent

​
Key Rule Categories

​
Critical Impact Rules

Eliminating Waterfalls

Impact: CRITICAL - 2-10× improvement
  • async-parallel - Promise.all() for independent operations
  • async-dependencies - better-all for partial dependencies
  • async-defer-await - Move await into branches
  • async-api-routes - Start promises early in API routes
  • async-suspense-boundaries - Strategic Suspense boundaries

Bundle Size

Impact: CRITICAL - Directly affects TTI and LCP
  • bundle-barrel-imports - Direct imports (200-800ms saved)
  • bundle-dynamic-imports - Use next/dynamic
  • bundle-defer-third-party - Load after hydration
  • bundle-conditional - Load only when needed
  • bundle-preload - Preload on hover/focus

​
High Impact Rules

Server-Side Performance

Impact: HIGH - Eliminates server waterfalls
  • server-auth-actions - Authenticate server actions
  • server-cache-react - React.cache() for deduplication
  • server-cache-lru - Cross-request caching
  • server-serialization - Minimize data passed to client
  • server-parallel-fetching - Parallel component fetches
  • server-dedup-props - Avoid duplicate serialization
  • server-after-nonblocking - Use after() for side effects

​
Example: Applying a Rule

async function Page() {
  const user = await fetchUser()
  const posts = await fetchPosts()
  const comments = await fetchComments()
  
  return <Dashboard user={user} posts={posts} comments={comments} />
}
Performance Impact: Changes from 3 sequential round trips to 1 parallel round trip - 3× faster on 100ms latency

​
When to Apply This Skill

The skill should be referenced when:

Writing New Code

  • Creating React components
  • Building Next.js pages
  • Implementing data fetching
  • Setting up API routes

Code Review

  • Reviewing for performance
  • Refactoring existing code
  • Optimizing bundle size
  • Reducing load times

​
Official Documentation

Learn More

  • Skills.sh Skill Page: vercel-react-best-practices
  • GitHub Source: Complete rules and examples in the skill directory
  • Vercel Engineering: Maintained by the Vercel team

​
Version Information

  • Skill Version: 1.0.0
  • Author: Vercel Engineering
  • License: MIT
  • Last Updated: January 2026

Build docs developers (and LLMs) love

Get started for freeTalk to us