App Router Fundamentals

There is no routes file. No array of paths, no decorator, no table in a config — you create a folder, put page.tsx in it, and the URL exists. The mechanism is segment matching: every directory level under app/ contributes exactly one URL segment, and the file that supplies the UI is the page inside the deepest matching folder.

app/
├── page.tsx                      →  /
├── pricing/page.tsx              →  /pricing
├── blog/
│   ├── page.tsx                  →  /blog
│   ├── first-post/page.tsx       →  /blog/first-post     (static beats dynamic)
│   └── [slug]/page.tsx           →  /blog/<anything-else>
├── docs/[...slug]/page.tsx       →  /docs/a  /docs/a/b       (required catch-all)
└── shop/[[...slug]]/page.tsx     →  /shop  /shop/a/b         (optional catch-all)

When a request for /blog/first-post arrives, Next walks the tree and prefers the static folder over [slug]; /blog/some-new-post falls through to the dynamic one. The general precedence is static → dynamic [x] → catch-all [...x] → optional catch-all [[...x]], which is why a catch-all can never shadow a concrete page — and why two folders that resolve to the same path (for example (a)/pricing and (b)/pricing) are a build error rather than a coin flip.

Note what a folder full of non-page files does: app/dashboard/layout.tsx with no page.tsx inside still produces no URL — visiting /dashboard returns 404, because the layout has nothing to wrap. Special files decorate a route; they never create one. And the matched params are not exclusive to the page: layout.tsx, template.tsx, loading.tsx, generateMetadata, and generateStaticParams in the same segment all receive the same params, so a tab strip can highlight the active slug without re-fetching anything.

The App Router's big version-specific change arrived with Next.js 15: params and searchParams are now Promises. The old synchronous params.slug was removed from the type surface, and reading it without awaiting yields an undefined that silently renders the wrong content:

// app/blog/[slug]/page.tsx — Next 15 shape
export default async function PostPage({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params          // ← the await is not optional
  const post = await getPost(slug)
  if (!post) notFound()
  return <article>{post.title}</article>
}

Skip the await and TypeScript complains (Property 'slug' does not exist on type 'Promise<{ slug: string }>'), or — in a JavaScript project with no types — you fetch /posts/undefined and ship a blank page. In a Client Component you never touch the Promise: useParams() from next/navigation returns the values directly.

Why async at all? Because the framework now needs to know when request data is resolved before it streams the rest of the tree; making params/searchParams/cookies()/headers() all Promises lets Next start rendering the shell before user-specific data settles. It is the same reasoning behind Suspense boundaries — streaming rather than blocking.

Versus the Pages Router, the comparison interviewers ask for:

Config decides what the server does — redirects, image hosts, headers — and stops short of routing, which is why the handoff from next.config Options lands here: folders, not functions, are how the App Router declares URLs.

Two files define behavior at a URL: page.tsx renders it for a human, route.ts answers it for a machine. A segment picks one. The page receives params and searchParams; the route exports HTTP methods:

// app/api/orders/route.ts
export async function GET(request: Request) {
  const orders = await db.order.findMany()
  return Response.json(orders)
}
export async function POST(request: Request) {
  const body = await request.json()
  // …
  return Response.json({ id: 'ord_123' }, { status: 201 })
}

One Next 15 behavior worth memorizing: GET Route Handlers are no longer cached by default (as of v14 they were) — every GET hits your code unless you opt in with export const revalidate = 60 or cache: 'force-cache' in the fetch. The same de-caching applied to fetch() itself: v15 flipped the default from force-cache to no-store, so data is fresh by default and staleness is now something you choose rather than remove.

Route Handlers get the same async treatment in Next 15 — the context object hands you params as a Promise, and you read a body with the standard Request API rather than a framework helper:

export async function GET(_req: NextRequest, ctx: { params: Promise<{ id: string }> }) {
  const { id } = await ctx.params
  return Response.json(await db.order.find(id))
}

Pages also export generateMetadata, which runs alongside the page and receives the same params — it is how per-route titles and Open Graph images are produced without a client-side document.title hack:

export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params
  const post = await getPost(slug)
  return { title: post.title, alternates: { canonical: `/blog/${slug}` } }
}

The bigger decision per route is static vs dynamic, controlled by exports at the top of the file (the "route segment config"):

export const dynamic = 'force-dynamic'   // 'auto' | 'force-static' | 'error'
export const revalidate = 60             // ISR: regenerate at most every 60s
export const runtime = 'nodejs'          // or 'edge'
export const dynamicParams = true        // unlisted params: render (true) or 404 (false)
export const maxDuration = 60            // ceiling for one invocation on serverless

With no config at all, Next prerenders the route at build time — the ○ in your build output — as long as nothing touches request-specific data. The things that force server-side rendering on demand:

• cookies() / headers() / connection() (all async in Next 15)
• reading searchParams in a page
• dynamic = 'force-dynamic'
• a fetch marked cache: 'no-store'

// Static candidate: no request data touched
export default async function AboutPage() {
  const { count } = await db.product.count()   // runs at build; ISR via `revalidate`
  return <p>{count} products</p>
}

// Dynamic: per-request by nature
export default async function CartPage({ searchParams }: {
  searchParams: Promise<{ coupon?: string }>
}) {
  const { coupon } = await searchParams       // user input → cannot be prerendered
  return <Cart coupon={coupon} />
}

runtime = 'edge' deserves a deliberate choice: edge invocations start faster and run close to the user, but they cannot load native modules (bcrypt, many DB drivers) and run in a restricted V8-derived environment — a Postgres driver simply fails there. Default to nodejs and switch only when you have a measured reason.

For interviews, "when is a route static?" is the same question with three correct triggers: no request APIs are read, no explicit dynamic opt-out, and any data call is cacheable — add one member from the list above and the route becomes dynamic. The mechanism that keeps dynamic segments sane when only some paths are prebuilt is generateStaticParams plus dynamicParams, and that is exactly where routes start 404-ing — the subject of the next chapter, with Root Layouts following it as the shell these pages render inside.

Most App Router debugging is a route that exists in your editor and not in production. Four causes account for nearly all of it.

1. Unlisted params with dynamicParams: false. Pre-rendering a dynamic route works in two halves: generateStaticParams() declares the paths to build, and dynamicParams decides what happens for everything else.

// app/products/[id]/page.tsx
export async function generateStaticParams() {
  return [{ id: 'sku-1' }, { id: 'sku-2' }]     // prerendered at build
}
export const dynamicParams = false               // any other id → 404

Default is true: unknown ids render on demand, per request. Flip it to false — a legitimate choice for a small catalog or an output: 'export' deployment — and every id you forgot to list returns 404, including the one the marketing team added this morning. The failure looks like missing data but is really a routing policy.

2. Case sensitivity. app/About/page.tsx and app/about/page.tsx are the same folder on Windows and macOS (case-insensitive filesystems) and two different folders on Linux. A project developed on Windows happily runs with Page.tsx instead of page.tsx, then returns 404 for the entire route once the build runs on a case-sensitive CI runner — and, worse, the preview environment that also runs Linux was broken from day one and nobody looked. Route files are lowercase by convention for this reason: page.tsx, layout.tsx, route.ts. Rename before the first deploy, not after the incident.

3. Duplicate or shadowed paths. Two route groups producing the same URL ((marketing)/pricing/page.tsx and (app)/pricing/page.tsx) cannot both win; the build flags the duplicate. A static folder also shadows a dynamic sibling (blog/first-post/ in front of blog/[slug]/) — brilliant when intended, baffling when a leftover test folder silently eats traffic from a real post.

4. Wrong tree level. The URL follows folders from app/, so app/(shop)/checkout/page.tsx is /checkout, while a stray extra directory — app/pages/checkout/page.tsx — is /pages/checkout. Both are visible in one glance at the build's route table, which is the fastest diagnostic there is:

Route (app)                         Size     First Load JS
┌ ● /blog/[slug]                    1.2 kB   94.5 kB

Not-found and error are different responses. notFound() throws a special error that not-found.tsx renders with a real 404 status — use it when the record does not exist. A crashed fetch or a thrown exception renders error.tsx with a 500. Serving a 200 page for a missing record is the SEO version of lying to your users: crawlers index dead links and keep sending traffic that bounces. Throw notFound() after your lookup misses, every time.

There is also a URL-shape cause worth ruling out cheaply: trailing slashes. If trailingSlash: true is set in next.config.ts but your links are built as /about/ versus /about, one form redirects and, behind certain CDNs that cache both variants, one can 404. Check curl -I on the failing URL before touching the folder tree — it distinguishes a routing problem from a URL-format problem in seconds.

The debugging order I would state in an interview: confirm a page.tsx exists at the segment path, check spelling including case, check precedence (static vs dynamic vs catch-all), then check dynamicParams, then check for duplicates introduced by route groups. If all of that is clean, the route probably is not missing at all — it is being redirected or rewritten by next.config.ts, which is why next.config Options is the right place to look before you start renaming folders. notFound() plus a colocated not-found.tsx is how a route reports "that record does not exist" with a real 404 status rather than a broken page. Once URLs are behaving, the next piece is the shell every page renders inside: Root Layouts.