react-performance

# React Performance Performance optimization patterns for React 18/19 and Next.js, adapted from [Vercel Labs `react-best-practices`](https://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices) (MIT, v1.0.0). This skill organizes rules by priority and provides decision-tree guidance for active code review and refactoring. ## When to Activate - Writing or reviewing React/Next.js code for performance - Diagnosing slow page loads, slow interactions, or high CPU on the client - Auditing bundle size or Lighthouse Core Web Vitals regressions - Removing waterfalls in Server Components / API routes - Reducing client-side re-renders - Optimizing long lists, animations, or hydration - Auditing optimization choices in PRs touching `app/`, `pages/`, `components/`, or data layers ## Priority Index | Priority | Category | Prefix | When it matters | |---|---|---|---| | 1 — CRITICAL | Eliminating Waterfalls | `async-` | Anytime `await` is followed by independent `await` | | 2 — CRITICAL | Bundle Size Optimization | `bundle-` | First-load JS, route-level imports, third-party libs | | 3 — HIGH | Server-Side Performance | `server-` | RSC, Server Actions, API routes, SSR | | 4 — MEDIUM-HIGH | Client-Side Data Fetching | `client-` | SWR / TanStack Query / raw `fetch` in hooks | | 5 — MEDIUM | Re-render Optimization | `rerender-` | High-frequency state updates, parent-child fan-out | | 6 — MEDIUM | Rendering Performance | `rendering-` | Long lists, animations, hydration | | 7 — LOW-MEDIUM | JavaScript Performance | `js-` | Hot loops, frequent allocations | | 8 — LOW | Advanced Patterns | `advanced-` | Effect-event integration, stable refs | ## 1. Eliminating Waterfalls (CRITICAL) > "Waterfalls are the #1 performance killer" — every sequential `await` adds full network latency. ### Cheap conditions before await Check sync conditions (props, env, hardcoded flags) before awaiting remote data. ```ts // INCORRECT async function Page({ id }: { id: string }) { const flag = await getFlag("show-page"); if (!flag || !id) return null; const data = await getData(id); // ... } // CORRECT — short-circuit on cheap sync condition first async function Page({ id }: { id: string }) { if (!id) return null; const flag = await getFlag("show-page"); if (!flag) return null; const data = await getData(id); } ``` ### Defer awaits until used Move `await` into the branch that uses it. ```ts // INCORRECT — awaits before deciding it needs the data const user = await getUser(id); if (mode === "guest") return renderGuest(); return renderUser(user); // CORRECT if (mode === "guest") return renderGuest(); const user = await getUser(id); return renderUser(user); ``` ### Promise.all for independent work ```ts // INCORRECT — sequential const user = await getUser(id); const posts = await getPosts(id); const followers = await getFollowers(id); // CORRECT — parallel const [user, posts, followers] = await Promise.all([ getUser(id), getPosts(id), getFollowers(id), ]); ``` ### Partial dependencies — start early, await late ```ts // CORRECT — kick off all promises, await only when each result is needed const userP = getUser(id); const postsP = getPosts(id); const profile = await getProfile(id); if (profile.private) return null; const [user, posts] = await Promise.all([userP, postsP]); ``` ### Suspense for streaming Push `<Suspense>` boundaries close to the data so the page paints what it can while slower sub-trees stream in. The trade-off: layout shift when content arrives — reserve space (skeleton or `min-height`). ### Server Components: parallel through composition ```tsx // INCORRECT — sibling awaits run sequentially inside one component export default async function Page() { const user = await getUser(); const cart = await getCart(); return <View user={user} cart={cart} />; } // CORRECT — split into children, React runs them in parallel export default async function Page() { return ( <View> <UserSection /> <CartSection /> </View> ); } ``` ## 2. Bundle Size Optimization (CRITICAL) ### Direct imports, not barrels Barrel `index.ts` files force the bundler to walk the entire module graph even when tree-shaking removes most of it. Direct imports save 200-800ms of first-load JS in many real-world apps. ```ts // INCORRECT import { Button, Card, Modal } from "@/components"; // CORRECT import { Button } from "@/components/Button"; import { Card } from "@/components/Card"; import { Modal } from "@/components/Modal"; ``` Next.js 13.5+ has [Optimize Package Imports](https://nextjs.org/docs/app/api-reference/next-config-js/optimizePackageImports) that automates this for listed packages — use it; manual direct imports still required for non-listed libs. ### Statically analyzable paths ```ts // INCORRECT — defeats bundler/trace analysis const mod = await import(`./pages/${name}`); // CORRECT — explicit per branch const mod = name === "home" ? await import("./pages/home") : await import("./pages/about"); ``` ### Dynamic imports for heavy components ```tsx import dynamic from "next/dynamic"; const HeavyChart = dynamic(() => import("./HeavyChart"), { loading: () => <Skeleton />, ssr: false, // when client-only }); ``` ### Defer third-party scripts Load analytics, logging, support widgets AFTER hydration. Use `next/script` with `strategy="afterInteractive"` (default) or `"lazyOnload"`. ### Conditional module loading ```tsx if (user.role === "admin") { const { AdminPanel } = await import("./admin/AdminPanel"); // ... } ``` ### Preload on hover/focus Trigger `<link rel="preload">` or `import()` on hover so the bundle is in cache by the time the user clicks. ## 3. Server-Side Performance (HIGH) ### Authenticate Server Actions like API routes Every `"use server"` function is a public endpoint. Authenticate AND authorize inside the action — never rely on the calling Client Component's gating. ```ts "use server"; export async function deleteUser(formData: FormData) { const session = await getSession(); if (!session?.user) throw new Error("Unauthorized"); const targetId = String(formData.get("id")); if (session.user.role !== "admin" && session.user.id !== targetId) { throw new Error("Forbidden"); } await db.user.delete({ where: { id: targetId } }); } ``` ### `React.cache()` for per-request deduplication ```ts import { cache } from "react"; export const getUser = cache(async (id: string) => { return db.user.findUnique({ where: { id } }); }); ``` `React.cache` dedupes within a single request. Calling `getUser("1")` from three Server Components in the same render = one DB query. ### LRU cache for cross-request data For data that does NOT change per request (config, lookup tables), cache outside React with an LRU cache or `unstable_cache`. ### Avoid duplicate serialization in RSC props When a Server Component renders the same data into multiple Client Components, the data is serialized once per consumer. Lift the Client Component up and pass children. ### Hoist static I/O to module scope ```ts // CORRECT — runs once at module load const fontData = readFileSync(fontPath); export async function Page() { return <Banner font={fontData} />; } ``` ### No mutable module-level state in RSC/SSR Module state on the server is shared across all requests — a race condition between users. Use request-scoped storage (`headers()`, `cookies()`, async context) instead. ### Minimize data passed to Client Components Only serialize what the Client needs. Strip fields, paginate, project columns at the DB layer. ### Parallelize nested fetches with Promise.all per item ```ts const users = await getUsers(); const enriched = await Promise.all( users.map(async (u) => ({ ...u, posts: await getPostsFor(u.id) })), ); ``` ### Use `after()` for non-blocking work Next.js 15 `after()` runs work after the response is sent — logging, cache warming, analytics. ```ts import { after } from "next/server"; export async function GET() { const data = await getData(); after(() => logAnalytics(data)); return Response.json(data); } ``` ## 4. Client-Side Data Fetching (MEDIUM-HIGH) ### SWR / TanStack Query for deduplication Multiple components calling `useUser(id)` should share one network request and one cache entry. Use SWR or TanStack Query — never roll your own `useEffect` + `fetch` for shared data. ### Deduplicate global event listeners ```tsx // INCORRECT — every component adds its own useEffect(() => { window.addEventListener("scroll", handler); return () => window.removeEventListener("scroll", handler); }, []); // CORRECT — single shared listener via a hook + global subject const useScroll = createScrollHook(); // singleton subject under the hood ``` ### Passive listeners for scroll ```ts window.addEventListener("scroll", handler, { passive: true }); ``` Improves scrolling smoothness; the listener cannot `preventDefault()`. ### localStorage: version + minimize - Always store a `version` field; bump on schema change and migrate or discard old data - Keep payloads small — `localStorage` is synchronous and blocks main thread ## 5. Re-render Optimization (MEDIUM) ### Don't subscribe to state used only in callbacks ```tsx // INCORRECT — re-renders every time count changes const count = useStore((s) => s.count); const handler = () => doSomething(count); // CORRECT — read once on call const handler = () => { const count = useStore.getState().count; doSomething(count); }; ``` ### Extract expensive work into memoized components ```tsx // CORRECT — child re-renders only when `items` changes const Heavy = memo(function Heavy({ items }: { items: Item[] }) { return <Chart data={transform(items)} />; }); ``` ### Hoist default non-primitive props ```tsx // INCORRECT — new array each render breaks memo <List items={items ?? []} /> // CORRECT const EMPTY: Item[] = []; <List items={items ?? EMPTY} /> ``` ### Primitive dependencies in effects ```tsx // INCORRECT — new object identity every render useEffect(() => {}, [{ id, name }]); // CORRECT — primitives useEffect(() => {}, [id, name]); ``` ### Subscribe to derived booleans, not raw values ```tsx // INCORRECT — re-renders for any cart change const cart = useStore((s) => s.cart); const hasItems = cart.length > 0; // CORRECT — re-renders only when emptiness flips const hasItems = useStore((s) => s.cart.length > 0); ``` ### Derive during render, never via `useEffect` ```tsx // INCORRECT const [full, setFull] = useState(""); useEffect(() => setFull(`${first} ${last}`), [first, last]); // CORRECT const full = `${first} ${last}`; ``` ### Functional `setState` for stable callbacks ```tsx // CORRECT const increment = useCallback(() => setCount((c) => c + 1), []); ``` ### Lazy state initializer for expensive values ```tsx const [tree] = useState(() => parseTree(largeInput)); ``` ### Avoid memo for simple primitives `useMemo(() => x + 1, [x])` is overhead. Memo earns its keep on object identity and expensive computation. ### Split hooks with independent deps ```tsx // INCORRECT — both selectors re-run if either source changes const { a, b } = useSomething(source1, source2); // CORRECT const a = useA(source1); const b = useB(source2); ``` ### Move interaction logic into event handlers Event handlers run only on the user action — `useEffect` re-runs whenever deps change. ### `startTransition` for non-urgent updates ```tsx const [pending, startTransition] = useTransition(); startTransition(() => setFilters(newFilters)); ``` ### `useDeferredValue` for expensive renders ```tsx const deferredQuery = useDeferredValue(query); const results = useMemo(() => expensiveSearch(deferredQuery), [deferredQuery]); ``` ### `useRef` for transient frequent values For values that change often but should not trigger re-render (timestamps, last-key, accumulators). ### Don't define components inside components