RonanCodes/skills/performance-first

Performance-first

The rule: a route transition must never wait for data. Click a link → the new page appears now with a skeleton that matches its final layout → data streams in and fills it. Spinners-on-blank and "freeze until loaded" are banned. This is a baseline for every app, not a late optimisation.

Why: perceived speed is navigation latency. A page that paints instantly (even as a skeleton) feels fast; one that hangs for 400ms on a query feels broken, no matter the real numbers.

TanStack Query is the DEFAULT client data layer (standing preference)

For ANY app with client-fetched data, use TanStack Query by default — its cache makes revisiting a page instant (served from cache, revalidated in the background), which is exactly the "snappy between pages" feel we want. Set it up at scaffold time, don't retrofit:

• A QueryClientProvider at the root; sensible defaults (staleTime ~30s, gcTime minutes, refetchOnWindowFocus off unless needed).
• Prefetch on intent (hover/focus a link → queryClient.prefetchQuery).
• Optimistic mutations (onMutate → cancel, snapshot, patch, rollback on error) so writes feel instant.
• This is the TanStack Start / SPA / client-data default.

The one caveat — Next.js App Router (RSC) apps: if pages are server components reading data on the server (e.g. RLS-bound Supabase reads in a page.tsx), the instant-nav job is already done by loading.tsx skeletons + <Link> prefetch + streaming — and bolting React Query over server-rendered pages is a downgrade (you'd lose RSC streaming + server auth). There, reach for TanStack Query only for the genuinely client-side, frequently-refetched islands (live lists, polled data, optimistic widgets), not the whole page. So: TanStack Query is the default for the client data layer; on RSC the route-level instant-nav comes from loading.tsx + prefetch. Pick per where the data is fetched, never rip out working server reads to force React Query in.

Shared principles (every stack)

1. Instant transition > complete data. Render the shell + skeleton on navigation; never await the whole page before painting.
2. Skeleton, not spinner. And the skeleton must match the final layout (same card shapes, counts, spacing) so there's no layout shift when data lands.
3. Prefetch on intent. Prefetch the route/data on hover/focus (and in-viewport links), so by the time they click it's warm.
4. Stale-while-revalidate. Show cached data instantly, refetch in the background. Revisiting a page should be instant.
5. Optimistic mutations. Reflect the user's action in the UI immediately; reconcile on the server response; roll back on error.
6. Lean bundles. Server components by default; dynamic()-import heavy/below-the-fold client code; keep the client JS small.
7. Measure. Watch Core Web Vitals (LCP, INP, CLS) + route-transition time; budget them.

Next.js App Router (e.g. the Makely / Vercel-aligned stack)

• loading.tsx per route segment — Next shows it instantly on navigation while the async server component resolves. This alone fixes "page hangs on data".
• <Suspense> boundaries around the slow parts with skeleton fallbacks → the static shell paints first, slow data streams in. Don't await everything at the top of the page component; isolate slow fetches in child components wrapped in Suspense.
• <Link> prefetches in-viewport routes in prod by default; keep links real <Link>s.
• useOptimistic (or useTransition + optimistic state) for server-action mutations so the UI updates before the round-trip.
• Skeleton components live next to the page; reuse the real card components' dimensions.

// app/agenda/loading.tsx  — instant on navigation, no data wait
export default function Loading() {
  return <div className="space-y-3">{[0,1,2].map(i => <div key={i} className="h-20 animate-pulse rounded-lg border bg-muted/40" />)}</div>;
}

TanStack Start / Router (the golden stack)

• Route loaders + defer() for slow data, with a pendingComponent (skeleton) on the route → the router renders pending UI instantly and resolves data after.
• TanStack Query as the client cache: set staleTime so revisiting is instant from cache; queryClient.prefetchQuery on hover/intent; background refetch keeps it fresh.
• <Await> to render deferred loader data with a Suspense-style fallback.
• Optimistic updates via useMutation onMutate + rollback in onError.

export const Route = createFileRoute('/bids')({
  loader: ({ context }) => ({ bids: defer(context.queryClient.ensureQueryData(bidsQuery)) }),
  pendingComponent: BidsSkeleton,
});

Apply / review checklist

• [ ] Every data-backed route has a loading.tsx (Next) or pendingComponent (TanStack).
• [ ] Slow sections are in <Suspense> / <Await>, not blocking the shell.
• [ ] Skeletons match the real layout (no CLS).
• [ ] Mutations are optimistic where the result is predictable.
• [ ] Repeat visits hit cache (staleTime / RSC cache), not a cold fetch.
• [ ] Heavy client code is dynamically imported.

Stack pairing

• Golden stack ([/ro:new-tanstack-app], [/ro:tanstack]): TanStack Router deferred loaders + TanStack Query.
• Next/Vercel stack ([/ro:nextjs]): loading.tsx + Suspense streaming + useOptimistic.
• Required baseline for the Makely build (see housapp-build-session).