---
name: react-best-practices
description: Use when writing, reviewing, or refactoring React/Next.js code in this repository, especially components, App Router pages, Server Actions, data fetching, bundle optimization, render performance, hydration, or UI responsiveness work.
---

# React Best Practices

## Overview

Apply Vercel's React and Next.js performance guidance to this repository. The upstream skill was inspected as a full directory, including `SKILL.md`, `README.md`, `metadata.json`, the generated `AGENTS.md`, and all source rule files under `rules/`.

## How to Use

Start with the highest-impact category that matches the task:

1. **Eliminating Waterfalls:** parallelize independent async work, defer awaits until needed, start promises early, and use Suspense boundaries deliberately.
2. **Bundle Size Optimization:** avoid broad imports where Next cannot optimize them, use `next/dynamic` for heavy UI, defer third-party client libraries, and keep dynamic paths statically analyzable.
3. **Server-Side Performance:** authenticate Server Actions like public API endpoints, avoid mutable request-scoped module state, minimize RSC-to-client serialization, dedupe per request with `React.cache()`, and hoist static I/O.
4. **Client Data & Rendering:** dedupe global listeners and requests, use passive scroll listeners, avoid derived-state effects, narrow effect dependencies, move interaction logic into handlers, and avoid inline component definitions.
5. **Hot Path JavaScript:** use early returns, `Set`/`Map` lookups, index maps, cached property reads, immutable `toSorted()`, and combined iterations only where the path is performance-sensitive.

For this Next/FSD repo, preserve the existing layer boundaries and public `index.ts` APIs while applying these patterns.

## References

- Full compiled guide: `references/vercel-react-best-practices-full.md`
- Source rules: `references/rules/*.md`
- Rule categories and impact: `references/rules/_sections.md`
- Upstream metadata and maintenance notes: `references/upstream/`

Read only the relevant rule files for the task. Use the compiled guide when a broader review needs cross-category context or examples.