React and Next.js performance optimization patterns adapted from Vercel Engineering's React Best Practices (https://github.com/vercel-labs/agent-skills). Organizes 70+ rules across 8 priority categories — waterfalls, bundle size, server-side, client fetching, re-render, rendering, JS micro-perf, advanced. Use when writing, reviewing, or refactoring React/Next.js code for performance.
origin
ECC
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
// INCORRECTasyncfunctionPage({ id }: { id: string }) {
const flag = awaitgetFlag("show-page");
if (!flag || !id) returnnull;
const data = awaitgetData(id);
// ...
}
// CORRECT — short-circuit on cheap sync condition firstasyncfunctionPage({ id }: { id: string }) {
if (!id) returnnull;
const flag = awaitgetFlag("show-page");
if (!flag) returnnull;
const data = awaitgetData(id);
}
Defer awaits until used
Move await into the branch that uses it.
// INCORRECT — awaits before deciding it needs the dataconst user = awaitgetUser(id);
if (mode === "guest") returnrenderGuest();
returnrenderUser(user);
// CORRECTif (mode === "guest") returnrenderGuest();
const user = awaitgetUser(id);
returnrenderUser(user);
// CORRECT — kick off all promises, await only when each result is neededconst userP = getUser(id);
const postsP = getPosts(id);
const profile = awaitgetProfile(id);
if (profile.private) returnnull;
const [user, posts] = awaitPromise.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 componentexportdefaultasyncfunctionPage() {
const user = awaitgetUser();
const cart = awaitgetCart();
return<Viewuser={user}cart={cart} />;
}
// CORRECT — split into children, React runs them in parallelexportdefaultasyncfunctionPage() {
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.
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 loadconst fontData = readFileSync(fontPath);
exportasyncfunctionPage() {
return<Bannerfont={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
Next.js 15 after() runs work after the response is sent — logging, cache warming, analytics.
import { after } from"next/server";
exportasyncfunctionGET() {
const data = awaitgetData();
after(() =>logAnalytics(data));
returnResponse.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 ownuseEffect(() => {
window.addEventListener("scroll", handler);
return() =>window.removeEventListener("scroll", handler);
}, []);
// CORRECT — single shared listener via a hook + global subjectconst useScroll = createScrollHook(); // singleton subject under the hood
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 changesconst { a, b } = useSomething(source1, source2);
// CORRECTconst 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.
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.
