Next.js Quick Reference

Analogy categoryAnalogies

This reference condenses the App Router's most-used file conventions, data-fetching APIs, and rendering rules into a single lookup page — useful when you already understand the concepts but need to quickly recall exact function names, file names, or config options mid-project. It assumes familiarity with the App Router (the app/ directory) rather than the legacy Pages Router.

🏏

Cricket analogy: It's like a fielding captain's laminated cheat card listing field placements for different match situations — not a coaching manual, just a fast lookup during play.

File Conventions

Inside the app/ directory, special files control behavior at each route segment: page.tsx defines the UI for a route and makes it publicly accessible, layout.tsx wraps child segments with shared UI that persists across navigation, loading.tsx provides an automatic Suspense fallback shown while a segment's data loads, error.tsx catches runtime errors in that segment (must be a Client Component), and route.ts defines an API endpoint by exporting HTTP-method functions like GET and POST instead of a default React component.

🏏

Cricket analogy: It's like a ground's designated zones: the pitch itself (page.tsx) is where play happens, the stadium roof (layout.tsx) covers every match played there, and the replay screen (loading.tsx) fills the gap during a drinks break.

text

app/
├── layout.tsx        # Root layout, wraps every page
├── page.tsx           # Route: /
├── loading.tsx        # Suspense fallback for /
├── error.tsx          # Error boundary for / (must be 'use client')
├── not-found.tsx      # Custom 404 UI
├── dashboard/
│   ├── layout.tsx     # Nested layout for /dashboard/*
│   ├── page.tsx        # Route: /dashboard
│   └── [id]/
│       └── page.tsx    # Route: /dashboard/:id (dynamic segment)
└── api/
    └── users/
        └── route.ts    # API route: /api/users (GET, POST, etc.)

Data Fetching and Caching Cheat Sheet

The extended fetch() API is the primary data-fetching primitive: fetch(url) caches indefinitely by default (equivalent to force-cache), fetch(url, { cache: 'no-store' }) disables caching and refetches every request, and fetch(url, { next: { revalidate: N } }) caches for N seconds before the next request triggers a background refresh. For mutations, generateStaticParams() pre-renders dynamic routes at build time, revalidatePath('/blog') and revalidateTag('posts') from next/cache invalidate cached data on demand, and both are typically called inside a Server Action or Route Handler right after a write operation completes.

🏏

Cricket analogy: It's like a scoreboard operator's three modes: print it once and never touch it again (force-cache), refresh it manually after every single ball (no-store), or refresh automatically every over on a timer (revalidate).

Quick decision rule: content that's identical for everyone and rarely changes → default fetch (cached). Content that must be fresh on every request (auth-dependent, real-time) → cache: 'no-store'. Content that changes periodically → { next: { revalidate: N } }.

Common Commands and Hooks

The core CLI commands are next dev (development server with hot reload), next build (production build), next start (run the production server), and next lint (run ESLint with Next.js's rule set). On the client side, useRouter() from next/navigation gives programmatic navigation (router.push(), router.refresh()), usePathname() returns the current URL path, useSearchParams() reads query parameters reactively, and redirect()/notFound() (importable in Server Components too) short-circuit rendering to send a redirect or trigger the nearest not-found.tsx.

🏏

Cricket analogy: It's like a captain's core toolkit: nets for practice (dev), the final XI selection (build), taking the field (start), and a pitch inspection report (lint) — each a distinct, essential step before and during a match.

typescript

'use client';
import { useRouter, usePathname, useSearchParams } from 'next/navigation';

export default function FilterBar() {
  const router = useRouter();
  const pathname = usePathname();
  const searchParams = useSearchParams();

  function setCategory(category: string) {
    const params = new URLSearchParams(searchParams);
    params.set('category', category);
    router.push(`${pathname}?${params.toString()}`);
  }

  return <button onClick={() => setCategory('electronics')}>Electronics</button>;
}

useSearchParams() opts a component into client-side rendering and requires a Suspense boundary around it when used in a page that's otherwise statically rendered, or Next.js will throw a build error about a missing Suspense boundary.

page.tsx, layout.tsx, loading.tsx, error.tsx, and route.ts are the core file conventions controlling each route segment.
route.ts defines API endpoints by exporting HTTP-method functions (GET, POST, etc.) instead of a default component.
fetch() defaults to cached (force-cache); use cache: 'no-store' for always-fresh data or { next: { revalidate: N } } for periodic refresh.
revalidatePath() and revalidateTag() from next/cache invalidate cached data on demand, typically after a mutation.
next dev, next build, next start, and next lint are the four core CLI commands.
useRouter(), usePathname(), and useSearchParams() from next/navigation handle client-side navigation and URL state.
useSearchParams() requires a Suspense boundary when used alongside static rendering, or the build will fail.