React Performance
Performance optimization patterns for React 18/19 and Next.js, adapted from Vercel Labs 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
awaitadds full network latency.
Cheap conditions before await
Check sync conditions (props, env, hardcoded flags) before awaiting remote data.
// 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.
// 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
// 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
// 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
// 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.
// 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 that automates this for listed packages — use it; manual direct imports still required for non-listed libs.
Statically analyzable paths
// 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
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
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.
"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
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
// 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
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.
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
// 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
window.addEventListener("scroll", handler, { passive: true });
Improves scrolling smoothness; the listener cannot preventDefault().
localStorage: version + minimize
- Always store a
versionfield; bump on schema change and migrate or discard old data - Keep payloads small —
localStorageis synchronous and blocks main thread
5. Re-render Optimization (MEDIUM)
Don't subscribe to state used only in callbacks
// 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
// 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
// INCORRECT — new array each render breaks memo
<List items={items ?? []} />
// CORRECT
const EMPTY: Item[] = [];
<List items={items ?? EMPTY} />
Primitive dependencies in effects
// INCORRECT — new object identity every render
useEffect(() => {}, [{ id, name }]);
// CORRECT — primitives
useEffect(() => {}, [id, name]);
Subscribe to derived booleans, not raw values
// 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
// INCORRECT
const [full, setFull] = useState("");
useEffect(() => setFull(`${first} ${last}`), [first, last]);
// CORRECT
const full = `${first} ${last}`;
Functional setState for stable callbacks
// CORRECT
const increment = useCallback(() => setCount((c) => c + 1), []);
Lazy state initializer for expensive values
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
// 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
const [pending, startTransition] = useTransition();
startTransition(() => setFilters(newFilters));
useDeferredValue for expensive renders
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
// INCORRECT — Inner is a new component on every Outer render
function Outer() {
const Inner = () => <span />;
return <Inner />;
}
Each render makes a new Inner type, defeating reconciliation and unmounting children.
6. Rendering Performance (MEDIUM)
Animate the wrapper, not the SVG
Transforming a <div> wrapper around an SVG is GPU-accelerated; transforming the SVG itself triggers paint.
content-visibility: auto for long lists
.row { content-visibility: auto; contain-intrinsic-size: auto 80px; }
Browser skips offscreen rendering — major win for lists with hundreds of rows.
Hoist static JSX
const STATIC_HEADER = <h1>Title</h1>;
function Page() {
return <>{STATIC_HEADER}<Body /></>;
}
SVG: reduce coordinate precision
d="M10.123456,20.654321" → d="M10.12,20.65". Each digit costs bytes; the visual difference is sub-pixel.
Hydration no-flicker via inline script
For values needed before hydration (theme, locale), inline a <script> that sets document.documentElement.dataset.* before React mounts.
Suppress expected hydration mismatches narrowly
<time suppressHydrationWarning>{new Date().toLocaleString()}</time>
Use ONLY for known-divergent leaf nodes — never on a tree containing other children.
<Activity> for show/hide instead of mount/unmount
React 19 <Activity mode="visible|hidden"> keeps tree state and effects mounted but hides — cheaper than unmount/remount for tabs and accordions.
Ternary over && for conditional render
// INCORRECT — `0` renders as text node
{count && <Badge>{count}</Badge>}
// CORRECT
{count > 0 ? <Badge>{count}</Badge> : null}
useTransition for loading states
Pair startTransition with the action; React shows the previous UI as isPending while the next state computes.
React DOM resource hints
import { preload, preconnect } from "react-dom";
preload("/api/critical", { as: "fetch" });
preconnect("https://api.example.com");
defer / async on <script> tags
defer for ordered execution after DOMContentLoaded; async for fire-and-forget.
7. JavaScript Performance (LOW-MEDIUM)
- Batch DOM/CSS changes — apply via class swap or
cssText, not property-by-property Mapfor repeated lookups —O(1)vsO(n)linear scan- Cache property access in loops —
const len = arr.length - Memoize pure functions — module-level
Map<key, result> - Cache
localStoragereads — sync API; one read per render - Combine
filter().map()into one pass —flatMapor singlefor - Check array length first before expensive comparisons
- Early return from functions
- Hoist RegExp out of loops — compilation is not free
- Loop for min/max instead of
sort()—O(n)vsO(n log n) Set/Mapfor membership —O(1)vsArray.includesO(n)toSorted()over mutation when immutability mattersflatMapto map and filter in one passrequestIdleCallbackfor non-critical work
8. Advanced Patterns (LOW)
useEffectEvent deps
Values from useEffectEvent are stable — do NOT add them to effect deps.
Event handler refs
For stable callbacks passed to memoized children:
const handlerRef = useRef(handler);
useEffect(() => { handlerRef.current = handler; });
const stable = useCallback((arg) => handlerRef.current(arg), []);
Init once per app load
For module-level singletons (telemetry, logger), guard with a module-scope flag — not useEffect.
useLatest for stable callback refs
function useLatest<T>(value: T) {
const ref = useRef(value);
ref.current = value;
return ref;
}
Automated Tools
Many of these rules are now automated:
- Next.js 13.5+ Optimize Package Imports — barrel import optimization
- React Compiler (RFC, in canary) — auto-memoization
- Turbopack — faster builds, better tree-shaking
- Bundle Analyzer (
@next/bundle-analyzer) — visualize first-load JS
When the project ships React Compiler, demote rerender-* manual memoization rules to "review-only" — the compiler handles them. Manual useMemo/useCallback becomes unnecessary noise.
Lighthouse / Web Vitals Mapping
| Metric | Most relevant categories |
|---|---|
| LCP (Largest Contentful Paint) | Waterfalls, Bundle Size, Resource Hints |
| INP (Interaction to Next Paint) | Re-render, Rendering, JavaScript |
| CLS (Cumulative Layout Shift) | Rendering (Suspense placement, image dimensions) |
| TBT (Total Blocking Time) | Bundle Size, JavaScript, Defer Third-Party |
| FID (legacy) | Bundle Size, Hydration |
Related
- Skills: react-patterns, react-testing, frontend-patterns, accessibility, nextjs-turbopack
- Rules: rules/react/
- Agents:
react-reviewerenforces these rules in code review;react-build-resolverhandles related build failures - Commands:
/react-review,/react-build,/react-test
Attribution
Adapted from Vercel Labs react-best-practices skill (MIT License, copyright Vercel Engineering, v1.0.0 January 2026). Source: https://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices.
This skill restructures and adapts the original 70-rule catalog into a single navigable reference. For the full original ruleset with extended examples, see the upstream repository.