Next.js API Reference for the App Router

If you've spent any time in the Next.js docs, you've probably noticed they're split into very different kinds of pages. Some walk you through building something step by step. Some explain a concept in the abstract, with no code at all. And some are just... a signature, a table of options, and a couple of examples — no narrative, no "why," just the facts. That last category is the API Reference, and it's worth understanding as its own thing rather than "the boring part of the docs you skip until you need it."

I want to use this article to map out what actually lives under API Reference in the App Router docs, how it's organized, and — more usefully — when you should be reaching for it instead of a Guide or a Getting Started page. Once you internalize the shape of it, you stop wasting time searching for things in the wrong place.

What "API Reference" Actually Means Here

Next.js's docs are organized into a rough hierarchy of intent:

• Getting Started teaches you the mental model — what a Server Component is, how routing works, why caching exists. You read it once, in order, to build a foundation.
• Guides solve a specific problem you already understand the shape of — "how do I add authentication," "how do I set up Playwright." You read the one guide you need, when you need it.
• API Reference documents a specific, named thing — a function, a file convention, a config option — exhaustively and precisely. You don't read it front to back. You look up the one entry you need, check its signature, its parameters, its caveats, and leave.

That last distinction matters more than it sounds like it should. A Guide answers "how do I accomplish X?" An API Reference entry answers "what exactly does revalidatePath do, what are its parameters, and what does it return?" You reach for a Guide when you're building something; you reach for API Reference when you already know what you're building and just need to confirm the contract of a specific tool.

This is also why API Reference pages read so differently from the rest of the docs. They're not written to be persuasive or to build intuition — they're written to be exhaustive and skimmable, because their job is to be correct at 2am when you're debugging something and need to know exactly what a third argument does.

How the App Router's API Surface Is Organized

The App Router's API Reference splits into nine subsections, and it's worth knowing what each one is actually for before you go looking for something in the wrong one:

Directives — the small set of string literals ('use client', 'use server', 'use cache', and its variants) that change how a file or function is compiled and where it executes. These are unusual because they're not functions you call or files you name — they're compiler instructions that live at the top of a file or function body.

Components — the built-in React components Next.js ships: <Image>, <Link>, <Script>, <Form>, and the font-loading utilities under next/font. These are things you import and render, same as any other React component, just with Next.js-specific optimizations baked in.

File-system conventions — this is the big one, and probably where most people spend the most reference-lookup time. Every special filename Next.js recognizes — page.js, layout.js, loading.js, error.js, route.js, and more — plus folder conventions like route groups ((name)), parallel routes (@slot), and intercepting routes ((.)segment). If you've ever wondered "does Next.js care what I name this file," the answer lives here.

Functions — the programmatic API you call from inside your code: cookies(), headers(), redirect(), notFound(), revalidatePath(), revalidateTag(), and dozens more, split roughly between server-only functions and client-side hooks like useRouter() and useSearchParams().

Configuration — everything that goes in next.config.js, plus TypeScript and ESLint setup. This is the largest single reference page in the entire docs by option count, and it's genuinely just a very long, well-organized lookup table.

CLI — the next command itself (next dev, next build, next start, next lint) and create-next-app, the scaffolding tool.

Adapters — a newer, more specialized section aimed at people building deployment platforms for Next.js, not people building Next.js apps. If you're not writing a hosting adapter, you can safely ignore this one entirely.

Edge Runtime and Turbopack — reference material for the two pieces of Next.js infrastructure that behave differently enough from "normal" Node.js and Webpack that they warrant their own dedicated pages: what APIs are and aren't available in the Edge Runtime, and what Turbopack's compiler actually does differently.

Directives: Where Your Code Runs

Directives deserve a special mention because they're the one category of "API" here that isn't a function or a file — it's a compiler signal. Get the mental model wrong and you'll misread half the reference pages that use them.

// A Client Component boundary
"use client";

import { useState } from "react";

export function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}

// A Server Function callable from the client
"use server";

export async function createPost(formData: FormData) {
  // runs only on the server, even when called from a Client Component
}

// A cached function or component
"use cache";

export async function getProduct(id: string) {
  return db.product.findUnique({ where: { id } });
}

Each of these strings tells the Next.js compiler something structural about the code that follows it — not "run this differently," but "this code lives on a different side of a boundary than you'd assume by default." That's why directive reference pages read more like language specifications than API docs: they're documenting compiler behavior, not runtime behavior.

File-System Conventions: The Vocabulary Next.js Reads

If Directives are about where code runs, file-system conventions are about what Next.js does when it sees a particular filename in a particular place. A typical route folder might look like this:

app/
  dashboard/
    layout.tsx       # persistent UI wrapping every page below it
    page.tsx         # the actual route content
    loading.tsx      # shown while page.tsx is loading
    error.tsx        # catches errors thrown by page.tsx or its children
    not-found.tsx     # shown when notFound() is called
    settings/
      page.tsx        # /dashboard/settings

None of these filenames are enforced by JavaScript or React — they're a convention Next.js's file-system router specifically looks for. That's exactly the kind of thing an API Reference page is built to document precisely: not "here's a nice pattern for organizing loading states" (that's a Guide's job), but "here is the exhaustive list of props loading.js receives, when it's rendered, and how it interacts with Suspense."

The same logic applies to folder-naming conventions like (marketing) route groups or @modal parallel route slots — they look like arbitrary punctuation until you've read the specific reference page explaining what each symbol means to the router.

Functions: The Programmatic API

This is the category most similar to a "normal" API reference — a list of functions, their signatures, and what they return.

import { cookies, headers } from "next/headers";
import { redirect } from "next/navigation";
import { revalidateTag } from "next/cache";

export async function updateSettings(formData: FormData) {
  const cookieStore = await cookies();
  const requestHeaders = await headers();

  // ...do the update...

  revalidateTag("settings");
  redirect("/dashboard/settings?saved=true");
}

What's easy to miss on a first pass through these reference pages: many of these functions only work in certain contexts. cookies() and headers() are server-only and, in recent versions, asynchronous — calling them from the wrong place, or forgetting the await, is one of the most common sources of confusing runtime errors for people migrating from older Next.js code. The reference page for each function is exactly where that context restriction is documented precisely, usually in a "Good to know" callout easy to skim past if you're skim-reading instead of reading.

Configuration, CLI, and Adapters: The Infrastructure Layer

next.config.js options, the CLI, and Adapters are all, in a sense, "outside" your application code — they configure how Next.js builds, runs, and deploys your app rather than how your app itself behaves. This is a useful mental distinction: if you're debugging why a page renders wrong, you're almost certainly in Functions or File-system conventions. If you're debugging why your build behaves wrong, or why a deployment platform doesn't support a feature you expected, you're in Configuration, CLI, or Adapters.

Adapters in particular are worth flagging because their existence surprises people: they're not for you unless you work at a hosting company building first-class Next.js support into a platform. If you're an app developer who stumbles onto the Adapters section while searching for something else, that's usually a sign you took a wrong turn — what you actually wanted is probably in Configuration or one of the deployment Guides instead.

When to Reach for API Reference vs. a Guide

Here's a concrete example of the distinction in practice. Say you want to add a contact form to your site.

The Guide ("Creating forms with Server Actions") walks you through the pattern: how to structure a form component, wire it to a Server Action, handle pending and error states, and validate input. You read it once, understand the shape of the solution, and adapt it to your form.

The API Reference entries you'll bounce between while actually writing the code are narrower: the <Form> component's props, whether useActionState takes one argument or two in this version, what redirect() does when called inside a Server Action versus a Route Handler. You're not reading these to learn a pattern — you already have the pattern from the Guide. You're checking a specific detail you're not 100% sure about.

In practice, most real feature work looks like: skim a Guide once for the shape of the solution, then keep API Reference open in another tab for the fifteen small lookups that happen while you actually type the code. Treating API Reference as something to "read" in the way you'd read a Guide is the wrong mental model — it's closer to a dictionary than a book.

A Practical Workflow for Using It Well

A few habits that make API Reference genuinely fast to use rather than a slog:

Search by exact name, not concept. If you know you're looking for generateStaticParams, search that literal string rather than "how do I pre-render dynamic routes" — reference pages are titled by their exact API name, and full-text search on the docs site is fast and precise for exact matches.

Check the "Version History" table before assuming current behavior. Many reference pages, especially for long-lived APIs like next.config.js options, include a table showing when a feature was added, when its behavior changed, and when it was deprecated. If something documented doesn't match what you're seeing, that table is usually why — you're likely on a different major version than the one the surrounding prose assumes.

Follow the "Related" links instead of searching again. Most reference pages end with a short list of related APIs — revalidateTag links to revalidatePath and cacheTag, for instance. When you're not sure which of several similar-sounding functions you actually need, these links are usually faster than a fresh search.

Don't read Configuration front-to-back. It's one enormous page by design, organized alphabetically so it's fast to Cmd+F through. Skimming it top to bottom looking for inspiration is the wrong use of it — you go there with a specific option name already in mind.

Key Takeaways

Section	What it documents	When you need it
Directives	Compiler-level code boundaries ('use client', 'use server', 'use cache')	Deciding where a piece of code should execute
Components	Built-in optimized components (<Image>, <Link>, <Script>, fonts)	Rendering something Next.js has a built-in optimized version of
File-system conventions	Special filenames and folder patterns the router recognizes	Naming or organizing files inside app/
Functions	The programmatic server/client API (cookies, redirect, useRouter, etc.)	Calling something from inside your own code
Configuration	Every next.config.js, TypeScript, and ESLint option	Changing build, routing, or tooling behavior
CLI	next commands and create-next-app	Running or scaffolding a project from the terminal
Adapters	Building deployment platform support for Next.js	Only relevant if you're building hosting infrastructure
Edge Runtime / Turbopack	What's available in the Edge runtime; what Turbopack changes	Debugging platform- or compiler-specific behavior

API Reference isn't meant to teach you Next.js — Getting Started and Guides do that job. It's meant to answer one precise question correctly, as fast as possible, once you already know roughly what you're looking for. Treat it that way, keep it open in a tab while you work rather than trying to study it, and it becomes one of the more genuinely useful parts of the whole documentation site rather than the part you dread clicking into.