Foundations — Cheat Sheet

Rendering Models — CSR, SSR, SSG, ISR and RSC

// CSR — Client-Side Rendering
//   The server sends an empty div. React builds the page in the browser.
//   + cheap to host, great for logged-in app screens
//   - blank until JS loads, weak for SEO, slow on a mid-range phone

// SSG — Static Site Generation (build time)
//   HTML produced once, at deploy, served from a CDN.
//   + fastest possible, cheapest, perfect SEO
//   - stale until the next deploy; not for per-user content
//   Next: the default for a route with no dynamic data.

// ISR — Incremental Static Regeneration
//   Static, but regenerated in the background every N seconds.
//   + CDN speed with fresh-enough content
//   - a user can see a stale copy for up to N seconds
export const revalidate = 3600

// SSR — Server-Side Rendering (per request)
//   HTML built on the server for each request.
//   + always fresh, personalised, SEO-friendly
//   - a server round trip on every visit; you pay for compute

// RSC — React Server Components (App Router)
//   Components that run ONLY on the server and stream their output.
//   Their code — and the libraries they import — never reach the browser.
//   This is the default in the App Router, not an opt-in.

The App Router — Files Are the Routing

app/
  layout.tsx            // root layout — REQUIRED, wraps everything
  page.tsx              // /
  loading.tsx           // Suspense fallback for this segment
  error.tsx             // error boundary ('use client', required)
  not-found.tsx         // 404 for this segment
  global-error.tsx      // catches errors in the root layout itself

  problems/
    page.tsx            // /problems
    loading.tsx         // shown while /problems streams
    [slug]/
      page.tsx          // /problems/two-sum
      opengraph-image.tsx

  api/
    health/route.ts     // GET /api/health — a handler, not a page

// Only page.tsx and route.ts make a segment publicly routable. A
// folder of components with no page.tsx is not a URL — which is why
// colocating components inside a route folder is safe.

// Dynamic segments
[slug]        // /problems/two-sum   -> params.slug
[...path]     // catch-all           -> params.path is an array
[[...path]]   // optional catch-all  -> also matches the parent

Server and Client Components

'use client'      // at the TOP of a file, before imports

// It means: this module and every module it imports goes into the
// client bundle. It does NOT mean "does not run on the server" —
// a client component still renders on the server for the initial
// HTML, then hydrates in the browser.

// The boundary is inherited DOWNWARD through imports:
// ClientThing.tsx has 'use client'
//   -> everything it imports is client too, even without the directive
// So one 'use client' at the top of a tree pulls the whole tree in.

// Server components cannot:
//   useState  useEffect  useRef  useContext
//   onClick and any event handler
//   window  document  localStorage
//   any browser-only library

// Client components cannot:
//   be async / await data directly
//   import server-only code (a database client, a secret)
//   read the filesystem

// The error that teaches this:
//   "You're importing a component that needs useState. It only works
//    in a Client Component, but none of its parents are marked with
//    'use client'."

Navigation — Link, useRouter and the Router Cache

import Link from 'next/link'

<Link href="/problems">Problems</Link>
<Link href={`/problems/${slug}`} prefetch={false}>Open</Link>
<Link href="/dashboard" replace>Go</Link>          // no history entry

// Link prefetches when it enters the viewport (production only), so
// the destination is often already loaded before the click. That is
// most of why App Router navigation feels instant.

// Programmatic — note the import path
'use client'
import { useRouter } from 'next/navigation'        // NOT next/router
const router = useRouter()
router.push('/problems/two-sum')
router.replace('/login')
router.back()
router.refresh()          // re-fetch the current route from the server

// Reading the current location, all from next/navigation:
const pathname = usePathname()                     // '/problems/two-sum'
const params = useParams()                         // { slug: 'two-sum' }
const search = useSearchParams()                   // read-only

// useSearchParams makes a client component dynamic, so wrap it in a
// Suspense boundary or the whole route opts out of static rendering.

Layouts, Loading States and Error Boundaries

// app/layout.tsx — the root. Required, and must render html and body.
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <Header />
        {children}
        <Footer />
      </body>
    </html>
  )
}

// app/(app)/dashboard/layout.tsx — nests inside the root
export default function DashboardLayout({ children }) {
  return <div className="grid grid-cols-[240px_1fr]"><Sidebar />{children}</div>
}

// Navigating /dashboard -> /dashboard/billing re-renders only the
// page. The sidebar is NOT re-rendered, so its scroll position, its
// open sections and any client state inside it survive.

// The corollary that surprises people: a layout does not re-run on
// navigation between its children, so data fetched in a layout is
// NOT refreshed by moving between them. Fetch per-page data in the
// page.

// template.tsx is the escape hatch — same shape, but a fresh instance
// on every navigation. Use it when you want an enter animation or
// state reset per route.

Project Structure and TypeScript Conventions

src/
  app/
    layout.tsx
    page.tsx
    problems/
      page.tsx
      loading.tsx
      _components/ProblemCard.tsx     // used by this route only
      _lib/format.ts
    (auth)/
      login/page.tsx
      register/page.tsx
    api/
      webhooks/razorpay/route.ts
  components/
    ui/Button.tsx                     // design-system primitives
    shared/EmptyState.tsx
  lib/
    api-client.ts                     // transport
    db.ts                             // server-only
    auth.ts
  features/
    problems/                         // domain logic used by several routes
      queries.ts
      actions.ts
      types.ts

// The rule: app/ describes URLs. Anything that is not about a URL —
// a domain model, a query, a shared component — belongs outside it.

// _folders are never routable, which is what makes colocation safe.
// Prefix server-only modules and enforce it:
import 'server-only'          // in lib/db.ts — a client import fails the build
import 'client-only'          // in a browser-API module

Hydration Errors and the Usual Traps

// 1. A value that differs between server and client
new Date().toLocaleString()      // server timezone vs the user's
Math.random()
Date.now()
// Fix: render it in an effect, or pass a fixed value down.

// 2. A browser API read during render
if (window.innerWidth < 768)     // ReferenceError on the server
localStorage.getItem('theme')    // undefined on the server
// Fix: read it in useEffect, and accept one frame of the default.

// 3. Invalid HTML nesting — the browser repairs it, React does not
<p><div>…</div></p>              // the browser closes the p early
<a><a>…</a></a>
<table><div/></table>
// This one is easy to miss, because the error points at hydration
// rather than at the markup.

// 4. Extensions that mutate the DOM before hydration
//    Password managers and translators add attributes to inputs.
//    Test in an incognito window before chasing your own code.

// 5. Locale or currency formatting without a fixed locale
new Intl.NumberFormat().format(n)          // varies by machine
new Intl.NumberFormat('en-IN').format(n)   // deterministic