OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add affaan-m/ecc --skill react-performance
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.
npx skills add affaan-m/ecc --skill 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.
app/, pages/, components/, or data layers| 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 |
"Waterfalls are the #1 performance killer" — every sequential
awaitadds full network latency.
Check sync conditions (props, env, hardcoded flags) before awaiting remote data.
Move await into the branch that uses it.
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).
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.
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.
Load analytics, logging, support widgets AFTER hydration. Use next/script with strategy="afterInteractive" (default) or "lazyOnload".
Trigger <link rel="preload"> or import() on hover so the bundle is in cache by the time the user clicks.
Every "use server" function is a public endpoint. Authenticate AND authorize inside the action — never rely on the calling Client Component's gating.
React.cache() for per-request deduplicationReact.cache dedupes within a single request. Calling getUser("1") from three Server Components in the same render = one DB query.
For data that does NOT change per request (config, lookup tables), cache outside React with an LRU cache or unstable_cache.
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.
Module state on the server is shared across all requests — a race condition between users. Use request-scoped storage (headers(), cookies(), async context) instead.
Only serialize what the Client needs. Strip fields, paginate, project columns at the DB layer.
after() for non-blocking workNext.js 15 after() runs work after the response is sent — logging, cache warming, analytics.
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.
Improves scrolling smoothness; the listener cannot preventDefault().
version field; bump on schema change and migrate or discard old datalocalStorage is synchronous and blocks main threaduseEffectsetState for stable callbacksuseMemo(() => x + 1, [x]) is overhead. Memo earns its keep on object identity and expensive computation.
Event handlers run only on the user action — useEffect re-runs whenever deps change.
startTransition for non-urgent updatesuseDeferredValue for expensive rendersuseRef for transient frequent valuesFor values that change often but should not trigger re-render (timestamps, last-key, accumulators).
Each render makes a new Inner type, defeating reconciliation and unmounting children.
Transforming a <div> wrapper around an SVG is GPU-accelerated; transforming the SVG itself triggers paint.
content-visibility: auto for long listsBrowser skips offscreen rendering — major win for lists with hundreds of rows.
d="M10.123456,20.654321" → d="M10.12,20.65". Each digit costs bytes; the visual difference is sub-pixel.
For values needed before hydration (theme, locale), inline a <script> that sets document.documentElement.dataset.* before React mounts.
Use ONLY for known-divergent leaf nodes — never on a tree containing other children.
<Activity> for show/hide instead of mount/unmountReact 19 <Activity mode="visible|hidden"> keeps tree state and effects mounted but hides — cheaper than unmount/remount for tabs and accordions.
&& for conditional renderuseTransition for loading statesPair startTransition with the action; React shows the previous UI as isPending while the next state computes.
defer / async on <script> tagsdefer for ordered execution after DOMContentLoaded; async for fire-and-forget.
cssText, not property-by-propertyMap for repeated lookups — O(1) vs O(n) linear scanconst len = arr.lengthMap<key, result>localStorage reads — sync API; one read per renderfilter().map() into one pass — flatMap or single forsort() — O(n) vs O(n log n)Set/Map for membership — O(1) vs Array.includes O(n)toSorted() over mutation when immutability mattersflatMap to map and filter in one passrequestIdleCallback for non-critical workuseEffectEvent depsValues from useEffectEvent are stable — do NOT add them to effect deps.
For stable callbacks passed to memoized children:
For module-level singletons (telemetry, logger), guard with a module-scope flag — not useEffect.
useLatest for stable callback refsMany of these rules are now automated:
@next/bundle-analyzer) — visualize first-load JSWhen the project ships React Compiler, demote rerender-* manual memoization rules to "review-only" — the compiler handles them. Manual useMemo/useCallback becomes unnecessary noise.
| 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 |
react-reviewer enforces these rules in code review; react-build-resolver handles related build failures/react-review, /react-build, /react-testAdapted 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.
// 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);// 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),
]);// 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]);// 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>
);
}// INCORRECT
import { Button, Card, Modal } from "@/components";
// CORRECT
import { Button } from "@/components/Button";
import { Card } from "@/components/Card";
import { Modal } from "@/components/Modal";// 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");import dynamic from "next/dynamic";
const HeavyChart = dynamic(() => import("./HeavyChart"), {
loading: () => <Skeleton />,
ssr: false, // when client-only
});if (user.role === "admin") {
const { AdminPanel } = await import("./admin/AdminPanel");
// ...
}"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 } });
}import { cache } from "react";
export const getUser = cache(async (id: string) => {
return db.user.findUnique({ where: { id } });
});// CORRECT — runs once at module load
const fontData = readFileSync(fontPath);
export async function Page() {
return <Banner font={fontData} />;
}const users = await getUsers();
const enriched = await Promise.all(
users.map(async (u) => ({ ...u, posts: await getPostsFor(u.id) })),
);import { after } from "next/server";
export async function GET() {
const data = await getData();
after(() => logAnalytics(data));
return Response.json(data);
}// 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 hoodwindow.addEventListener("scroll", handler, { passive: true });// 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);
};// CORRECT — child re-renders only when `items` changes
const Heavy = memo(function Heavy({ items }: { items: Item[] }) {
return <Chart data={transform(items)} />;
});// INCORRECT — new array each render breaks memo
<List items={items ?? []} />
// CORRECT
const EMPTY: Item[] = [];
<List items={items ?? EMPTY} />// INCORRECT — new object identity every render
useEffect(() => {}, [{ id, name }]);
// CORRECT — primitives
useEffect(() => {}, [id, name]);// 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);// INCORRECT
const [full, setFull] = useState("");
useEffect(() => setFull(`${first} ${last}`), [first, last]);
// CORRECT
const full = `${first} ${last}`;// CORRECT
const increment = useCallback(() => setCount((c) => c + 1), []);const [tree] = useState(() => parseTree(largeInput));// INCORRECT — both selectors re-run if either source changes
const { a, b } = useSomething(source1, source2);
// CORRECT
const a = useA(source1);
const b = useB(source2);const [pending, startTransition] = useTransition();
startTransition(() => setFilters(newFilters));const deferredQuery = useDeferredValue(query);
const results = useMemo(() => expensiveSearch(deferredQuery), [deferredQuery]);// INCORRECT — Inner is a new component on every Outer render
function Outer() {
const Inner = () => <span />;
return <Inner />;
}.row { content-visibility: auto; contain-intrinsic-size: auto 80px; }const STATIC_HEADER = <h1>Title</h1>;
function Page() {
return <>{STATIC_HEADER}<Body /></>;
}<time suppressHydrationWarning>{new Date().toLocaleString()}</time>// INCORRECT — `0` renders as text node
{count && <Badge>{count}</Badge>}
// CORRECT
{count > 0 ? <Badge>{count}</Badge> : null}import { preload, preconnect } from "react-dom";
preload("/api/critical", { as: "fetch" });
preconnect("https://api.example.com");const handlerRef = useRef(handler);
useEffect(() => { handlerRef.current = handler; });
const stable = useCallback((arg) => handlerRef.current(arg), []);function useLatest<T>(value: T) {
const ref = useRef(value);
ref.current = value;
return ref;
}