performance

Quick Reference

Memoization Rules

• NEVER memoize without profiling evidence
• React.memo: only when component receives same props but parent re-renders
• useMemo: only for expensive computations (>1ms) with stable deps
• useCallback: only when passed as prop to memoized child component
• If you can't explain WHY it needs memoization, remove it

Code Splitting

// Route-level splitting (always do this)
const Dashboard = React.lazy(() => import('./pages/Dashboard'));
// Next.js
const Chart = dynamic(() => import('./components/Chart'), { ssr: false });

RTK Query Performance

// ✅ selectFromResult — only re-render when YOUR data changes
const { user } = useGetUsersQuery(undefined, {
  selectFromResult: ({ data }) => ({ user: data?.find(u => u.id === id) }),
});

// ✅ Appropriate cache times
keepUnusedDataFor: 300,     // 5 min for stable data
pollingInterval: 30000,     // 30s for live data
refetchOnMountOrArgChange: 60, // re-fetch if >60s stale

Barrel Imports

// BAD: imports entire library (200-800ms in dev)
import { Check, X, ChevronDown } from 'lucide-react';
// GOOD: direct imports
import Check from 'lucide-react/dist/esm/icons/check';
// GOOD: Next.js optimizePackageImports
// next.config.js: experimental: { optimizePackageImports: ['lucide-react'] }

Known barrel-heavy libraries: lucide-react, @mui/material, lodash, date-fns, react-icons.

React Compiler

If React Compiler is enabled (babel-plugin-react-compiler or react-compiler-runtime in deps), memo(), useMemo(), useCallback() are handled automatically. Remove manual memoization to reduce noise.

Core Web Vitals Targets

• LCP < 2.5s | INP < 200ms | CLS < 0.1

Waterfall Elimination

Sequential awaits are the #1 server performance killer. Independent async operations must run in parallel.

// BAD: sequential — total time = a + b + c
const users = await getUsers();
const posts = await getPosts();
const comments = await getComments();

// GOOD (async-parallel): parallel — total time = max(a, b, c), 2-10x faster
const [users, posts, comments] = await Promise.all([
  getUsers(),
  getPosts(),
  getComments(),
]);

// GOOD (async-dependencies): start early, await late
const usersPromise = getUsers();       // starts immediately
const config = await getConfig();       // needed first
const users = await usersPromise;       // already in flight

// GOOD (async-api-routes): kick off fetches before unrelated work
export async function GET(request: Request) {
  const dataPromise = fetchExternalData();  // start fetch
  const session = await getSession();       // do auth meanwhile
  if (!session) return unauthorized();
  const data = await dataPromise;           // fetch likely done already
  return Response.json(data);
}

// GOOD (async-defer-await): await only in branches that need the value
const resultPromise = expensiveComputation();
if (condition) {
  return quickPath();                       // never awaits
}
const result = await resultPromise;         // only awaited when needed

async-suspense-boundaries: Wrap async Server Components in <Suspense> to stream progressively. Without boundaries, the entire page blocks on the slowest component.

// BAD: entire page waits for slowest component
export default async function Page() {
  return (
    <div>
      <SlowChart />    {/* 3s — blocks everything */}
      <FastSidebar />  {/* 100ms — waits for chart */}
    </div>
  );
}

// GOOD: fast parts stream immediately, slow parts show fallback
export default function Page() {
  return (
    <div>
      <Suspense fallback={<ChartSkeleton />}>
        <SlowChart />
      </Suspense>
      <FastSidebar />  {/* renders immediately */}
    </div>
  );
}

Bundle Optimization

// bundle-conditional: dynamic import inside event handler / feature flag
const handleExport = async () => {
  const { exportToPDF } = await import('./exportToPDF');
  exportToPDF(data);
};

// bundle-defer-third-party: load analytics AFTER hydration
useEffect(() => {
  import('./analytics').then(({ init }) => init());
}, []);
// Or Next.js: <Script src="analytics.js" strategy="afterInteractive" />

// bundle-preload: preload on hover for perceived instant navigation
<Link
  href="/dashboard"
  prefetch={true}                    // Next.js built-in
  onMouseEnter={() => import('./pages/Dashboard')}  // manual preload
>
  Dashboard
</Link>

Rendering Performance

/* rendering-content-visibility: skip rendering of off-screen sections */
.long-list-item {
  content-visibility: auto;
  contain-intrinsic-size: auto 200px;  /* estimated height */
}

rendering-hydration-no-flicker: Inline a small <script> for client-only data (theme, auth state) to prevent FOUC. The script runs before React hydrates.

<!-- In <head> or before React root -->
<script>
  // Prevents theme flash — runs before paint
  document.documentElement.dataset.theme =
    localStorage.getItem('theme') || 'system';
</script>

For detailed patterns, see references/ directory.