react-best-practices

---
name: react-best-practices
description: React best-practices reviewer for TSX files. Triggers after editing multiple TSX components to run a condensed quality checklist covering component structure, hooks usage, accessibility, performance, and TypeScript patterns.
metadata:
  priority: 4
  docs:
    - "https://react.dev/reference/react"
    - "https://react.dev/learn"
  pathPatterns:
    - 'src/components/**/*.tsx'
    - 'src/components/**/*.jsx'
    - 'app/components/**/*.tsx'
    - 'app/components/**/*.jsx'
    - 'components/**/*.tsx'
    - 'components/**/*.jsx'
    - 'src/ui/**/*.tsx'
    - 'lib/components/**/*.tsx'
  bashPatterns: []
  importPatterns:
    - 'react'
    - 'react-dom'
validate:
  -
    pattern: 'from\s+[''"](styled-components|@emotion/styled|@emotion/react|@mui/material|@chakra-ui/react)[''"]|styled\.'
    message: 'Legacy CSS-in-JS or component library detected. Consider shadcn/ui + Tailwind for modern Vercel-native UI.'
    severity: warn
    skipIfFileContains: '@/components/ui|shadcn|tailwindcss'
retrieval:
  aliases:
    - react review
    - component quality
    - tsx linter
    - react patterns
  intents:
    - review react code
    - improve component quality
    - check accessibility
    - optimize react
  entities:
    - hooks
    - accessibility
    - React
    - TSX
    - component
---

# Vercel React Best Practices

Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 70 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

## When to Apply

Reference these guidelines when:
- Writing new React components or Next.js pages
- Implementing data fetching (client or server-side)
- Reviewing code for performance issues
- Refactoring existing React/Next.js code
- Optimizing bundle size or load times

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
| 3 | Server-Side Performance | HIGH | `server-` |
| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
| 5 | Re-render Optimization | MEDIUM | `rerender-` |
| 6 | Rendering Performance | MEDIUM | `rendering-` |
| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
| 8 | Advanced Patterns | LOW | `advanced-` |

## Quick Reference

### 1. Eliminating Waterfalls (CRITICAL)

- `async-cheap-condition-before-await` - Check cheap sync conditions before awaiting flags or remote values
- `async-defer-await` - Move await into branches where actually used
- `async-parallel` - Use Promise.all() for independent operations
- `async-dependencies` - Use better-all for partial dependencies
- `async-api-routes` - Start promises early, await late in API routes
- `async-suspense-boundaries` - Use Suspense to stream content

### 2. Bundle Size Optimization (CRITICAL)

- `bundle-barrel-imports` - Import directly, avoid barrel files
- `bundle-analyzable-paths` - Prefer statically analyzable import and file-system paths to avoid broad bundles and traces
- `bundle-dynamic-imports` - Use next/dynamic for heavy components
- `bundle-defer-third-party` - Load analytics/logging after hydration
- `bundle-conditional` - Load modules only when feature is activated
- `bundle-preload` - Preload on hover/focus for perceived speed

### 3. Server-Side Performance (HIGH)

- `server-auth-actions` - Authenticate server actions like API routes
- `server-cache-react` - Use React.cache() for per-request deduplication
- `server-cache-lru` - Use LRU cache for cross-request caching
- `server-dedup-props` - Avoid duplicate serialization in RSC props
- `server-hoist-static-io` - Hoist static I/O (fonts, logos) to module level
- `server-no-shared-module-state` - Avoid module-level mutable request state in RSC/SSR
- `server-serialization` - Minimize data passed to client components
- `server-parallel-fetching` - Restructure components to parallelize fetches
- `server-parallel-nested-fetching` - Chain nested fetches per item in Promise.all
- `server-after-nonblocking` - Use after() for non-blocking operations

### 4. Client-Side Data Fetching (MEDIUM-HIGH)

- `client-swr-dedup` - Use SWR for automatic request deduplication
- `client-event-listeners` - Deduplicate global event listeners
- `client-passive-event-listeners` - Use passive listeners for scroll
- `client-localstorage-schema` - Version and minimize localStorage data

### 5. Re-render Optimization (MEDIUM)

- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
- `rerender-memo` - Extract expensive work into memoized components
- `rerender-memo-with-default-value` - Hoist default non-primitive props
- `rerender-dependencies` - Use primitive dependencies in effects
- `rerender-derived-state` - Subscribe to derived booleans, not raw values
- `rerender-derived-state-no-effect` - Derive state during render, not effects
- `rerender-functional-setstate` - Use functional setState for stable callbacks
- `rerender-lazy-state-init` - Pass function to useState for expensive values
- `rerender-simple-expression-in-memo` - Avoid memo for simple primitives
- `rerender-split-combined-hooks` - Split hooks with independent dependencies
- `rerender-move-effect-to-event` - Put interaction logic in event handlers
- `rerender-transitions` - Use startTransition for non-urgent updates
- `rerender-use-deferred-value` - Defer expensive renders to keep input responsive
- `rerender-use-ref-transient-values` - Use refs for transient frequent values
- `rerender-no-inline-components` - Don't define components inside components

### 6. Rendering Performance (MEDIUM)

- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
- `rendering-content-visibility` - Use content-visibility for long lists
- `rendering-hoist-jsx` - Extract static JSX outside components
- `rendering-svg-precision` - Reduce SVG coordinate precision
- `rendering-hydration-no-flicker` - Use inline script for client-only data
- `rendering-hydration-suppress-warning` - Suppress expected mismatches
- `rendering-activity` - Use Activity component for show/hide
- `rendering-conditional-render` - Use ternary, not && for conditionals
- `rendering-usetransition-loading` - Prefer useTransition for loading state
- `rendering-resource-hints` - Use React DOM resource hints for preloading
- `rendering-script-defer-async` - Use defer or async on script tags

### 7. JavaScript Performance (LOW-MEDIUM)

- `js-batch-dom-css` - Group CSS changes via classes or cssText
- `js-index-maps` - Build Map for repeated lookups
- `js-cache-property-access` - Cache object properties in loops
- `js-cache-function-results` - Cache function results in module-level Map
- `js-cache-storage` - Cache localStorage/sessionStorage reads
- `js-combine-iterations` - Combine multiple filter/map into one loop
- `js-length-check-first` - Check array length before expensive comparison
- `js-early-exit` - Return early from functions
- `js-hoist-regexp` - Hoist RegExp creation outside loops
- `js-min-max-loop` - Use loop for min/max instead of sort
- `js-set-map-lookups` - Use Set/Map for O(1) lookups
- `js-tosorted-immutable` - Use toSorted() for immutability
- `js-flatmap-filter` - Use flatMap to map and filter in one pass
- `js-request-idle-callback` - Defer non-critical work to browser idle time

### 8. Advanced Patterns (LOW)

- `advanced-effect-event-deps` - Don't put `useEffectEvent` results in effect deps
- `advanced-event-handler-refs` - Store event handlers in refs
- `advanced-init-once` - Initialize app once per app load
- `advanced-use-latest` - useLatest for stable callback refs

## How to Use

Read individual rule files for detailed explanations and code examples:

```
rules/async-parallel.md
rules/bundle-barrel-imports.md
```

Each rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and references

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`

From vercel/vercel-plugin at 2a1e58d, shown as plain text under its license: Apache-2.0 (permissive). The license text is in LICENSE.

• SKILL.md8.1 KB · 5c1b1512e764
• .vercel.approvers15 B · bcb7f202bef2
• AGENTS.md108 KB · fc93e7421177
• overlay.yaml1.3 KB · a7ecfc25e9ec
• rules/
• _sections.md1.6 KB · 01c59969e4e8
• _template.md631 B · 99df2a3ea088
• advanced-effect-event-deps.md1.8 KB · 55ed8f9f27a1
• advanced-event-handler-refs.md1.5 KB · a3097edeecfb
• advanced-init-once.md958 B · 3e4dc22173eb
• advanced-use-latest.md1.1 KB · 8a3f64dfe5a7
• async-api-routes.md1.1 KB · 523338540d73
• async-cheap-condition-before-await.md1.2 KB · 03107c1f70a2
• async-defer-await.md2.2 KB · f3c142d09061
• async-dependencies.md1.3 KB · 16ef469f877e
• async-parallel.md654 B · 6d2f84189627
• async-suspense-boundaries.md2.5 KB · de05fedac2eb
• bundle-analyzable-paths.md2.4 KB · 62090b5c815f
• bundle-barrel-imports.md2.8 KB · e648f6d54525
• bundle-conditional.md949 B · 09c8259c3efb
• bundle-defer-third-party.md920 B · 3719fb47b191
• bundle-dynamic-imports.md791 B · 401817a7369f
• bundle-preload.md1.1 KB · d1f7cc28da7c
• client-event-listeners.md2.0 KB · 242a873349fe
• client-localstorage-schema.md1.9 KB · 0fb7cdf9dc93
• client-passive-event-listeners.md1.6 KB · 1f35016f9053
• client-swr-dedup.md1.2 KB · 644652c39c6c
• js-batch-dom-css.md3.3 KB · 480b891b9eaf
• js-cache-function-results.md1.9 KB · 3daaa11d24f4
• js-cache-property-access.md532 B · 73e47431e748
• js-cache-storage.md1.7 KB · 11b826b04338
• js-combine-iterations.md753 B · 71add08aeeb4
• js-early-exit.md1.1 KB · 925ce5ce87f3
• js-flatmap-filter.md1.4 KB · 9e5b166a4191
• js-hoist-regexp.md1.0 KB · f9e9aef2f7c2
• js-index-maps.md837 B · 5df1bdc2cfab
• js-length-check-first.md1.7 KB · 8b54a311c826
• js-min-max-loop.md2.3 KB · 87dfb67e2f39
• js-request-idle-callback.md2.6 KB · ee08f83905b4
• js-set-map-lookups.md532 B · a7fd781a6ba9
• js-tosorted-immutable.md1.8 KB · d0a5e1b0fec4
• rendering-activity.md564 B · 1e5e7eaf3555
• rendering-animate-svg-wrapper.md1.2 KB · 9c6ae0ca7a51
• rendering-conditional-render.md980 B · 2ec2fa23c414
• rendering-content-visibility.md815 B · 64eee6d5b916
• rendering-hoist-jsx.md1.0 KB · 93b229560fae
• rendering-hydration-no-flicker.md2.3 KB · dc7ab358c67c
• rendering-hydration-suppress-warning.md872 B · 915bacb934e2
• rendering-resource-hints.md2.5 KB · 351b1095d641
• rendering-script-defer-async.md1.9 KB · 4cea07b7875b
• rendering-svg-precision.md588 B · ed468533f6e9
• rendering-usetransition-loading.md2.1 KB · 3a1249c3f130
• rerender-defer-reads.md973 B · 234050a77faf
• rerender-dependencies.md824 B · 17eb5830956f
• rerender-derived-state-no-effect.md1.2 KB · cb11ec76f50a
• rerender-derived-state.md728 B · 1c326bb67b01
• rerender-functional-setstate.md3.0 KB · 5e68df6b2ae8
• rerender-lazy-state-init.md2.0 KB · 4ae844740f26
• rerender-memo-with-default-value.md1.2 KB · 81c47476564a
• rerender-memo.md1.1 KB · 1f258990c2f2
• rerender-move-effect-to-event.md1.3 KB · abc2cbf167be
• rerender-no-inline-components.md2.1 KB · 1cc32907a770
• rerender-simple-expression-in-memo.md1.0 KB · 5bdcf2d1558b
• rerender-split-combined-hooks.md1.8 KB · 6f45d7033434
• rerender-transitions.md1.1 KB · 60f4033909a6
• rerender-use-deferred-value.md1.8 KB · 8c3579576a61
• rerender-use-ref-transient-values.md1.7 KB · f1a649af9d1d
• server-after-nonblocking.md2.0 KB · d0b8d24a3db9
• server-auth-actions.md2.6 KB · a2ca8aa10283
• server-cache-lru.md1.4 KB · 1924b6456184
• server-cache-react.md2.2 KB · fddeea6c870b
• server-dedup-props.md2.1 KB · c2747424cdac
• server-hoist-static-io.md4.4 KB · 5abea4dd882b
• server-no-shared-module-state.md1.8 KB · 4d869bf1cd2f
• server-parallel-fetching.md1.6 KB · 569a2e9fc04f
• server-parallel-nested-fetching.md992 B · ad5d9656984d
• server-serialization.md996 B · f4c7d68b29c8

76 files, 228 KB in total. Each file has a sha256 in the pin's manifest; the first 12 characters are shown.