Client Navigation APIs

## The two kinds of navigation Every route change in a web app is one of two things. A **document navigation** is what the browser does natively: it tears down the current page, requests a new HTML document, parses it, downloads and executes the scripts again, and hydrates from scratch. A **client-side navigation** keeps the same document alive and mutates the page in place, changing the URL through the History API rather than by loading a new document. A plain `<a href="/dashboard">` gives you the first. `<Link href="/dashboard">` from `next/link` gives you the second. ## What `<Link>` actually renders In the App Router, `<Link>` renders an ordinary `<a>` element into the DOM with the `href` you passed. That matters more than it sounds: middle-click, Ctrl/Cmd-click, "open in new tab", "copy link address", and crawlers all keep working, because there is a genuine anchor with a genuine URL under it. Next does not replace the anchor with a `<span>` and a click handler. What `<Link>` adds is a click listener. For a plain left-click with no modifier keys on a same-origin, in-app URL, it calls `preventDefault()` and routes the navigation through Next's client router. Modifier-clicks are left alone so the browser's native behaviour survives. ```tsx import Link from 'next/link'; export default function Nav() { return <Link href="/dashboard">Dashboard</Link>; } ``` ## What travels over the wire On a client-side navigation the router does not ask for HTML. It asks the server for the **React Server Component payload** for the destination route — a compact serialized description of the rendered server tree. Next then reconciles that payload into the tree already mounted in the browser. The App Router is segment-aware, so it only needs the segments that changed. Navigating from `/settings/profile` to `/settings/billing` when both sit under the same `app/settings/layout.tsx` fetches the new page segment; the shared layout above it is not re-requested and not re-rendered. That is why client components mounted in a shared layout — an open sidebar, a video player, a scroll container — keep their state across the navigation, while a plain anchor would destroy all of it. Prefetching amplifies this. In production builds, Next prefetches the destination when the link scrolls into the viewport and stores the result in the client-side Router Cache, so by the time the user clicks, the payload is frequently already in memory and the transition is immediate. ## What survives, and what does not Survives a `<Link>` navigation: - the JavaScript heap: module state, Zustand/Redux stores, in-memory caches - `useState` in components that are not unmounted (notably anything in a shared layout) - the loaded and parsed bundles — no re-download, no re-hydration of the whole app Does not survive: state inside the page segment being replaced, since that subtree unmounts. And nothing at all survives a plain `<a>`, because the JavaScript context itself is thrown away. ## When a plain anchor is still correct - **External or cross-origin URLs.** There is nothing for the App Router to render, so use `<a href="https://status.example.com">`. (Passing an external URL to `<Link>` degrades to a normal anchor navigation anyway, but a plain `<a>` states the intent.) - **Routes not owned by this Next app** — a legacy subpath, a file download, an endpoint that returns a PDF. - **When you genuinely want a hard reset**, for example after a logout that must discard every scrap of in-memory state. ## Common mistakes Wrapping a `<Link>` around an `<a>` is a legacy Pages Router pattern; in the App Router it produces nested anchors, which is invalid HTML. Just put the content directly inside `<Link>`. Calling `<Link>` "just an `<a>` with prefetch" misses the point — prefetch is an optimization, but the substantive difference is that the navigation never leaves the document. Finally, `<Link>` is not a replacement for programmatic navigation. When the destination depends on the outcome of some work — after a form submit, after an async check — you navigate with `useRouter().push()` from `next/navigation`, or with `redirect()` on the server.