Awesome-vibe-coding react-best-practices

React and Next.js performance optimization guidelines from Vercel Engineering. Use when writing, reviewing, or refactoring React/Next.js code — components, data fetching, bundle size, or performance.

install

source · Clone the upstream repo

git clone https://github.com/adriannoes/awesome-vibe-coding

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/adriannoes/awesome-vibe-coding "$T" && mkdir -p ~/.claude/skills && cp -r "$T/cursor/skills/react-best-practices" ~/.claude/skills/adriannoes-awesome-vibe-coding-react-best-practices && rm -rf "$T"

manifest: cursor/skills/react-best-practices/SKILL.md

source content

Source: vercel-labs/agent-skills —

skills/react-best-practices/

(MIT). Rule markdown files and

AGENTS.md

remain upstream; this file is a portable summary. Refresh from upstream periodically or run

npx skills add vercel-labs/agent-skills

Vercel React Best Practices

Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 69 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


async-
bundle-
server-
client-
rerender-
rendering-
js-
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-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 (full detail upstream)

Rule files with incorrect/correct examples are not copied into this repo. Open or fetch them from:

Directory (browse on GitHub): https://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices/rules

Raw rule file:

https://raw.githubusercontent.com/vercel-labs/agent-skills/main/skills/react-best-practices/rules/<rule-id>.md

(replace

<rule-id>

with IDs listed above, e.g.

async-parallel.md

)

Compiled guide (all rules expanded): https://raw.githubusercontent.com/vercel-labs/agent-skills/main/skills/react-best-practices/AGENTS.md

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-`