Next.js Routing (App Router)

1The Router Is the File System

There's no route-definition file to maintain — the folder structure under app/ is the route table. A folder maps to a URL segment; a page.tsx inside it makes that segment navigable.

app/
  page.tsx              → /
  about/page.tsx         → /about
  blog/page.tsx           → /blog
  blog/[slug]/page.tsx     → /blog/:slug   (dynamic segment)

2Dynamic Segments

// app/blog/[slug]/page.tsx
export default async function BlogPost({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  return <h1>Post: {slug}</h1>;
}

[slug] captures one path segment. Visiting /blog/hello-world renders this page with params.slug === "hello-world". In current Next.js versions, params is a Promise — it must be awaited (a change from earlier versions where it was a plain object), because Next.js needs to support cases where the value isn't known synchronously.

3Catch-All and Optional Catch-All Segments

app/docs/[...slug]/page.tsx      → /docs/a, /docs/a/b, /docs/a/b/c ...  (one or more segments)
app/docs/[[...slug]]/page.tsx    → /docs, /docs/a, /docs/a/b ...        (zero or more segments)

// app/docs/[...slug]/page.tsx
export default async function Docs({ params }: { params: Promise<{ slug: string[] }> }) {
  const { slug } = await params; // e.g. ["a", "b", "c"] for /docs/a/b/c
  return <p>Path: {slug.join("/")}</p>;
}

4Special Files Per Segment

// app/blog/loading.tsx
export default function Loading() {
  return <p>Loading posts...</p>;
}

// app/blog/error.tsx
"use client";

export default function Error({ error, reset }: { error: Error; reset: () => void }) {
  return (
    <div>
      <p>Something went wrong: {error.message}</p>
      <button onClick={() => reset()}>Try again</button>
    </div>
  );
}

Next.js automatically wraps a segment's page.tsx in a <Suspense> boundary using its sibling loading.tsx as the fallback, and in an error boundary using error.tsx — you don't write the boundary components yourself.

5Route Groups — Organize Without Affecting the URL

app/
  (marketing)/
    about/page.tsx    → /about   (the "(marketing)" segment is invisible in the URL)
    contact/page.tsx    → /contact
  (shop)/
    products/page.tsx    → /products

Parentheses around a folder name ((marketing)) create a route group: it organizes files and can hold its own layout.tsx applying only to routes inside it, but contributes nothing to the URL path.

6Parallel Routes and Intercepting Routes (Advanced)

app/
  @analytics/page.tsx
  @team/page.tsx
  layout.tsx

// app/layout.tsx
export default function Layout({
  children,
  analytics,
  team,
}: {
  children: React.ReactNode;
  analytics: React.ReactNode;
  team: React.ReactNode;
}) {
  return (
    <>
      {children}
      {analytics}
      {team}
    </>
  );
}

A @folder is a parallel route slot — the layout receives it as a named prop and can render multiple independent, simultaneously-active pages in the same layout (dashboards with independently loading widgets are the canonical use case).

7Navigating Between Routes

import Link from "next/link";

<Link href="/about">About</Link>;

"use client";
import { useRouter } from "next/navigation";

function BackButton() {
  const router = useRouter();
  return <button onClick={() => router.back()}>Go back</button>;
}

<Link> is the primary navigation primitive — it prefetches the target route's code (and, for static routes, its rendered payload) when it scrolls into view, and performs a client-side transition instead of a full page reload. useRouter() (from next/navigation, not the old next/router) gives imperative navigation (push, replace, back, refresh) for use inside event handlers.

<RootLayout>
  <BlogLayout>
    <BlogPostPage params={{ slug: "hello-world" }} />
  </BlogLayout>
</RootLayout>

⚠️ Common Pitfalls

1. Forgetting params is a Promise in current versions — params.slug directly (without await) either errors or silently gives you a Promise object instead of the string; always await params (or use(params) in a Client Component) first.
2. Putting page.tsx where you meant a layout-only route group — any folder with a page.tsx becomes a real, navigable URL segment; use (groupName) parentheses if you only want organization/shared layout without a URL segment.
3. Expecting error.tsx to catch errors in its own parent layout — an error boundary only catches errors from its children, so an error thrown inside the layout above error.tsx propagates further up to the nearest ancestor error.tsx instead.
4. Overusing catch-all routes for what should be separate pages — [...slug] is powerful but pushes all matching logic into runtime code (usually a CMS lookup); prefer explicit segments when the set of routes is known ahead of time.
5. Not providing a loading.tsx and being surprised navigation feels like it "hangs" — without it, the whole segment (and everything under it) waits for all data before showing anything, instead of streaming a fallback immediately.

📋 Quick Reference

app/page.tsx                    → /
app/about/page.tsx               → /about
app/blog/[slug]/page.tsx          → /blog/:slug        (params.slug)
app/docs/[...slug]/page.tsx        → /docs/a/b/c ...     (params.slug: string[])
app/docs/[[...slug]]/page.tsx       → /docs, /docs/a ...  (optional catch-all)
app/(group)/...                      → organizational only, no URL segment
app/@slot/page.tsx                    → parallel route, injected as a named layout prop
layout.tsx / loading.tsx / error.tsx / not-found.tsx / route.ts  → per-segment special files
<Link href="...">                      → prefetching client-side navigation
useRouter() from "next/navigation"      → imperative navigation (push/replace/back/refresh)

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

✅ Check yourself

Source: fe_nextjs_routing_theory.md · generated by tools/build_lessons.py