react-best-practices

# React Best Practices

Practical React and Next.js guidance for performance-sensitive product work.

This skill is a self-contained distillation of the Vercel React performance guidance so it can be installed and used directly inside Spellbook.

## When To Use

Use this skill when the user asks to:
- build or refactor React components
- improve Next.js performance
- reduce bundle size
- remove data-fetch waterfalls
- fix expensive rerenders
- review frontend code for performance issues

## Priority Order

Always check higher-priority categories first.

| Priority | Category | Focus |
|----------|----------|-------|
| 1 | Waterfalls | start async work early, await late, parallelize independent fetches |
| 2 | Bundle size | avoid barrel imports, defer heavy code, split by feature |
| 3 | Server-side performance | dedupe work, minimize serialization, prefer server execution |
| 4 | Client data fetching | dedupe requests, avoid redundant listeners and client churn |
| 5 | Rerenders | reduce subscriptions, stabilize dependencies, move expensive work |
| 6 | Rendering | avoid hydration flicker, reduce DOM/SVG cost, optimize long lists |
| 7 | JavaScript hot paths | cache repeated lookups, combine iterations, exit early |
| 8 | Advanced patterns | stable refs and callback patterns for edge cases |

## Hard Rules

### 1. Eliminate Waterfalls First

- Start independent requests in parallel.
- Do not serialize async work unless there is a real dependency.
- In API routes and server components, create promises early and await them as late as possible.
- Use Suspense boundaries when streaming content helps unblock rendering.

### 2. Protect Bundle Size

- Prefer direct imports over barrel files on hot paths.
- Use dynamic imports for heavy or infrequently used components.
- Defer analytics, logging, and other non-critical third-party code until after hydration.
- Load optional modules only when the related feature is activated.

### 3. Prefer Server Work Over Client Work

- Keep data fetching and heavy transformation on the server when possible.
- Minimize data serialized into client components.
- Cache server-side repeated work when the request model allows it.

### 4. Control Rerenders

- Subscribe only to the state needed for rendering.
- Use primitive effect dependencies where possible.
- Use functional `setState` when it removes unstable dependencies.
- Initialize expensive state lazily.
- Use `startTransition` for non-urgent UI updates.

### 5. Optimize Rendering Paths

- Use virtualization or `content-visibility` for long lists when appropriate.
- Avoid animating heavy SVG nodes directly when a wrapper works.
- Hoist static JSX outside render paths when it is truly constant.
- Prefer explicit ternaries over brittle `&&` branches when rendering conditions matter.

### 6. Clean Up JavaScript Hot Spots

- Build `Map` or `Set` for repeated membership checks.
- Cache repeated property access or derived results in tight loops.
- Combine adjacent `filter` / `map` passes when the path is performance-sensitive.
- Return early from branches instead of carrying unnecessary work forward.

## Review Checklist

When reviewing React or Next.js code, check for:

1. Any sequential async calls that could be parallelized
2. Barrel imports or large dependencies in hot components
3. Data fetched on the client that could move to the server
4. Effects or callbacks with unstable object/function dependencies
5. Repeated list scans where `Map` or `Set` would help
6. User-visible loading or hydration flicker

## Output Expectations

When using this skill, the output should:
- identify the highest-impact category first
- explain why the current pattern is costly
- propose the smallest effective change
- include concrete verification ideas such as bundle diff, profiler, or render-count checks

## References

- React docs: `react.dev`
- Next.js docs: `nextjs.org`
- SWR docs: `swr.vercel.app`
- Vercel engineering performance posts