Next.js Guides

If you've spent any time in the official Next.js documentation, you've probably noticed it's split into a few distinct zones that don't behave the same way. Getting Started reads like a tutorial — it assumes nothing and walks you through building a mental model of the framework, one concept at a time, in a fixed order. API Reference reads like a dictionary — you go there because you already know the name of the thing you need (generateMetadata, cookies(), next.config.js's images key) and you want its exact signature and options. Guides is neither of those. It's the messy, practical middle: a collection of roughly forty standalone how-tos, each one written to answer a specific question a real project eventually runs into, that don't need to be read in order and mostly don't reference each other.

That structure is genuinely useful once you understand it, but it also means the Guides section is easy to get lost in. There's no narrative thread connecting "How to set a Content Security Policy" to "How to build multi-tenant apps" to "How to optimize memory usage" — they just happen to live in the same folder because they're all things people building production Next.js apps eventually need to solve. This article is the map I wish existed the first time I went looking for something in there: what the category is for, how the guides are actually organized once you group them by the problem they solve rather than alphabetically, and which ones assume you already know things the docs don't always spell out up front.

What Makes a "Guide" Different From a Getting Started Page

The practical difference comes down to scope and assumed context. A Getting Started page teaches you a concept from zero — "Fetching Data" assumes you don't yet know how fetch behaves inside a Server Component, so it explains the rendering model before it explains the API. A Guide assumes you already have that foundation and skips straight to solving a specific, often narrow problem: "I need my Next.js app to talk to Redis for a custom cache handler," or "I need to configure my CI pipeline so it doesn't rebuild from scratch every time."

This matters for how you should approach them. If you open a Guide and find yourself confused by a term it uses without explaining — Server Components, the App Router's caching model, Route Handlers — that's not the Guide's fault. It's assuming you've already been through Getting Started, or at least the relevant slice of it. Bookmark the term, go read the Getting Started page that covers it, and come back. Guides are written for people mid-project, not people mid-tutorial.

The other distinguishing trait is that Guides are opinionated in a way API Reference deliberately isn't. API Reference documents what a function can do — every parameter, every edge case. A Guide tells you what to actually do in a given situation, including recommending one approach over other technically valid ones. "How to implement authentication in Next.js" doesn't just list every possible session-storage strategy; it walks you toward a specific, currently-recommended pattern (checking session state in Data Access Layer functions close to where data is used, rather than gating entire routes centrally). That's editorial judgment, and it's exactly what makes Guides valuable — but it also means a Guide's advice can shift between Next.js versions as the framework's recommended patterns evolve, more than an API Reference entry's exact function signature typically does.

How to Navigate Forty Guides Without Reading All of Them

Nobody sits down and reads the entire Guides section front to back — it isn't written to be consumed that way, and most of it won't be relevant to any single project. The efficient approach is to treat it like a reference shelf you pull one book off of when you hit a specific wall.

A few patterns for finding the right one fast:

Search by the problem, not the feature name. If you're trying to figure out why your build takes forever in CI, you might not know the guide is called "CI Build Caching" — you might search "next build slow github actions" and land there indirectly. The guide titles are mostly literal and problem-oriented (the docs favor "How to X" phrasing for most of them), which makes them reasonably search-friendly, but don't assume you'll guess the exact title on the first try.

Notice when two guides cover the "same" topic differently. This is the single most confusing thing about this section, and it's worth understanding upfront rather than discovering by accident: several pairs of guides exist because Next.js's caching model changed between versions, and both the old and new approaches are documented side by side rather than one replacing the other outright. More on this below — it's important enough to get its own section.

Treat migration guides as one-way doors, not casual reading. The guides under "Migrating" (from Create React App, from Vite, from Pages Router to App Router) are written as project checklists, not concept explainers. If you're not actively migrating something, skip them — they won't teach you much about Next.js in the abstract, they're optimized for someone doing the migration in real time with both codebases open.

Use the platform-specific guides only when they apply to you. Guides like "Deploying to Platforms," "Self-Hosting," and the PPR Platform Guide are written for different audiences — respectively, app developers picking a host, app developers running their own infrastructure, and platform engineers building hosting infrastructure for other people's Next.js apps. Reading the wrong one for your situation will actively confuse you about what you need to do.

The Guides, Grouped by What You're Actually Trying to Do

Here's the full set, organized by the problem they solve rather than the order they happen to appear in the sidebar. I've added a sentence of real context to each beyond the docs' one-line summary, since that's usually enough to tell whether it's the guide you need right now.

Data, Caching, and Revalidation

This is the largest cluster, and also where the "two eras" problem shows up most. Next.js 16 introduced Cache Components (the cacheComponents config flag and the use cache directive) as the new caching model, but plenty of existing codebases still run on the older, implicit fetch-based caching model — so the docs maintain guides for both.

• How Revalidation Works — the conceptual deep dive into the tag-based invalidation system: how revalidateTag and time-based expiry interact, and how consistency is maintained across multiple server instances. Read this before you build anything caching-adjacent; it explains the mental model everything else in this cluster assumes.
• ISR and ISR with Cache Components — two versions of the same underlying idea (regenerating static pages after deployment, without a full rebuild), written for the pre— and post—Cache Components world respectively. Check which caching model your project uses before picking one.
• Caching (Previous Model) — an explicit guide for projects that haven't adopted Cache Components, covering fetch options, unstable_cache, and route segment configs. If your project predates Cache Components or you've deliberately opted out, this is your caching reference, not the newer use cache material found elsewhere in the docs.
• CDN Caching — a level up from application caching: how a CDN sitting in front of your Next.js deployment interacts with the cache headers Next.js emits, including where cache variability currently falls short of pathname-based keying.
• CI Build Caching — narrower and more mechanical: how to configure your CI provider (GitHub Actions, GitLab CI, etc.) so next build reuses cached artifacts between runs instead of starting cold every time.

Authentication, Security, and Data Protection

• Authentication and Authentication with Cache Components — again a two-track pair. The core recommendation across both — keep authorization checks close to the data access code that needs them, in a dedicated Data Access Layer, rather than centralizing everything in Proxy — stays consistent, but the Cache Components version adds specific guidance on caching data derived from a user's session without accidentally leaking one user's cached data to another.
• Data Security — the built-in guardrails Next.js gives you for keeping server-only data off the client: the server-only package, taint APIs, and the general principle that anything imported into a Client Component's module graph ships to the browser whether you intended it to or not.
• Content Security Policy — how to generate a per-request nonce and wire it through next.config.js headers and your root layout so inline scripts (including the ones Next.js itself injects) don't get blocked by a strict CSP.

Styling and UI

• CSS-in-JS, Sass, Tailwind CSS v3 — three different styling approaches, each with its own setup guide. Note that Tailwind v4 (which this project actually uses) isn't covered by a dedicated Guide the same way v3 is — v4's setup lives more in the Getting Started CSS page, since v4's zero-config PostCSS approach needs less hand-holding than v3 did.
• Preventing Flash — specifically about correcting server-rendered content before the browser's first paint, most commonly relevant for theme switching (dark/light mode) where the server can't know the client's preference ahead of time.

Rendering, Navigation, and Perceived Performance

• Rendering Philosophy — the closest thing to a unifying theory in this whole section: Next.js treats static and dynamic rendering as a spectrum applied per-component, not a single global setting per route. Worth reading even if you don't have an immediate problem to solve, because it reframes how several other guides make sense.
• Prefetching, Optimizing prefetching, Instant navigation, Adopting Partial Prefetching — a cluster of closely related guides about making navigation feel instantaneous by loading route data before the user clicks. They build on each other rather than standing alone: Prefetching explains the baseline mechanism, the other three cover specific tuning problems (resolving per-link dynamic data, structuring routes for maximum prerendering, and migrating onto the newer partial-prefetch behavior).
• Preserving UI state — how React's Activity component keeps component state alive across navigations that would otherwise unmount and remount a subtree, and which parts of that state you can choose to reset versus keep.
• Streaming — progressively sending HTML to the browser as slower data resolves, using Suspense boundaries, rather than blocking the entire response on the slowest piece of data.
• View transitions — using the View Transitions API to animate between route states in a way that communicates meaning (this item moved, this section replaced that one) rather than just being decorative.

Interactivity and Forms

• Forms, Server Actions, Interactive apps — a natural reading order if you're building anything with user input. Forms covers the concrete "here's how you wire up a <form> to a Server Action" pattern; Server Actions goes underneath the hood of how that actually executes (the single-roundtrip model, why actions dispatch sequentially rather than in parallel, and how caching interacts with a mutation); Interactive apps zooms out further to optimistic UI, transitions, and pending-state feedback across a whole interface, not just one form.
• Offline support — a guide that exists precisely because Server Actions introduce a new failure mode traditional client-rendered apps didn't have as sharply: what happens to a mutation the user submitted right as their network dropped, and how to communicate that state instead of silently failing.

Internationalization, Metadata, and Discoverability

• Internationalization — routing and content localization for multi-language sites; deliberately doesn't prescribe a translation library, just the routing conventions.
• JSON-LD — structured data for search engines and, increasingly, AI crawlers — a small guide but one that's easy to skip past even though it's a quick win for content-heavy sites.
• Public pages — patterns for building pages that are the same for every visitor (marketing pages, blog listings, product catalogs) and can therefore be optimized much more aggressively than personalized, per-user pages.

Performance, Bundle Size, and Resource Loading

• Lazy Loading, Package Bundling, Third Party Libraries — the trio to reach for when your JavaScript bundle is bigger than it should be. Lazy Loading is about deferring imports until they're needed; Package Bundling is about analyzing what's actually in your bundles (via the Turbopack or Webpack bundle analyzer); Third Party Libraries specifically covers the @next/third-parties package, which ships pre-optimized wrappers for common embeds like Google Maps and Google Tag Manager, so you don't have to hand-roll the lazy-loading logic yourself for those specific cases.
• Scripts — the general-purpose next/script component and its loading strategies, for any third-party script that doesn't have a dedicated @next/third-parties wrapper.
• Videos — recommendations specific to serving and optimizing video, which doesn't get the same automatic treatment next/image gives to images.
• Memory Usage — diagnosing and reducing memory consumption both in local development (where a large project's dev server can balloon over a long session) and in production.

Multi-App and Multi-Tenant Architectures

• Multi-tenant — serving different customers or brands from a single codebase and deployment, typically keyed by subdomain or custom domain.
• Multi-zones — the opposite problem: splitting one large application across multiple independently deployed Next.js apps that appear to visitors as a single site, commonly used for large orgs where different teams own different sections of the same domain.
• Backend for Frontend — using Next.js primarily as an API/orchestration layer in front of other backend services, rather than as the primary UI renderer.

Observability and Debugging

• Debugging — configuring source maps and breakpoints for VS Code, Chrome DevTools, and Firefox DevTools against both the server and client halves of a Next.js process.
• Instrumentation and OpenTelemetry — running code at server startup (for setting up monitoring, feature flags, or metrics before the first request arrives) and wiring that instrumentation into a full OpenTelemetry pipeline for distributed tracing.

Development Environment and Tooling

• Development Environment — practical tuning for your local dev server experience specifically (this is distinct from Memory Usage's broader scope, though they overlap).
• AI Coding Agents and Next.js MCP Server — two guides aimed squarely at making AI tools like this one work better against your specific codebase: configuring your project so an agent pulls current documentation instead of relying on outdated training data, and exposing your running app's state to an agent via MCP for more accurate debugging assistance.
• MDX — configuring Markdown-with-JSX support, relevant if your content (blog posts, docs) needs to embed live React components inline.

Deployment and Infrastructure

• Building — what actually happens during next build, and how to read its output (route types, bundle sizes, warnings) to catch problems before they reach production.
• Deploying to Platforms — a decision framework for which hosting platform to pick, based on which Next.js features (ISR, Route Handlers, Proxy, Adapters) a given platform's infrastructure can actually support.
• Self-Hosting — running Next.js yourself, whether as a long-running Node.js server, inside Docker, or as a fully static export, without relying on a managed platform.
• Static Exports and SPAs — related but distinct: Static Exports is about producing a folder of static HTML/JS/CSS with no server required at all; SPAs is about deliberately opting out of server rendering in favor of a traditional client-rendered single-page app shape, which is a stricter and more specific choice than a static export implies.
• PWAs — turning your app into an installable Progressive Web App with offline caching via a service worker.
• PPR Platform Guide — written for people building the hosting platform itself, not the app on top of it; covers implementing Partial Prerendering support at the infrastructure level.

Migrating to (or Within) Next.js

• Migrating, plus its specific sub-guides for Create React App, Vite, and moving from the Pages Router to the App Router — these are the ones I mentioned earlier that read as checklists rather than concept pieces. Go in expecting a step-by-step process, not an explainer.
• Migrating to Cache Components — a different kind of migration: not between frameworks, but between Next.js's own older and newer caching models, moving route segment configs over to the use cache directive.

Testing

• Testing is the overview page, and it fans out into four framework-specific guides — Cypress, Jest, Playwright, and Vitest. None of these prescribe which tool to use; the overview page is mostly a decision aid (Cypress and Playwright for end-to-end, Jest and Vitest for unit testing, with some overlap in what each can technically do), and the specific guide for whichever tool you pick handles the actual next.config.js and test-runner wiring.

Production Readiness

• Production — the closest thing to a final checklist before shipping: a rundown of performance, security, and UX recommendations to review before a Next.js app goes live, mostly linking back into the more specific guides above rather than introducing new material of its own.

The Split You'll Run Into Most Often: Cache Components or Not

If there's one piece of context worth internalizing before you start reading Guides seriously, it's this: Next.js 16 changed its caching model, and the docs haven't (and likely won't) delete the guidance for the old one, because plenty of production apps still run on it. That means several guides exist in pairs, and picking the wrong half of the pair will actively mislead you about how your own app behaves.

// next.config.js — this one flag is the fork in the road
/** @type {import('next').NextConfig} */
const nextConfig = {
  cacheComponents: true, // if this is true, you're in Cache Components territory
};

module.exports = nextConfig;

If cacheComponents is enabled in your next.config.js, you want the guides written for that model: "ISR with Cache Components," "Authentication with Cache Components," and the use cache / cacheLife / cacheTag APIs described throughout Getting Started's own Caching page. If it isn't set, or you haven't touched it, you're most likely still on the implicit fetch-caching model, and "Caching (Previous Model)" is the guide that actually describes your app's current behavior — reading the Cache Components version instead will describe APIs that don't do anything in your project yet.

This single check — one boolean in one config file — resolves more confusion than any other piece of context in this entire section, and it's worth confirming before you go chasing a caching bug through the wrong guide.

A Couple of Patterns Worth Seeing Directly

Two small examples that come up constantly enough to be worth showing here rather than sending you straight to the dedicated guide.

A minimal CSP header wired through next.config.js, generating a per-request nonce (the actual guide covers this in far more depth, including how to read the nonce back out in your root layout):

// next.config.js
const nextConfig = {
  async headers() {
    return [
      {
        source: "/(.*)",
        headers: [
          {
            key: "Content-Security-Policy",
            value: "default-src 'self'; script-src 'self' 'nonce-{NONCE}'",
          },
        ],
      },
    ];
  },
};

module.exports = nextConfig;

And the shape of a form wired to a Server Action, which is the entry point most of the Interactivity cluster above assumes you already recognize:

// app/contact/actions.ts
"use server";

export async function submitContact(formData: FormData) {
  const email = formData.get("email");
  // validate, persist, etc.
}

// app/contact/page.tsx
import { submitContact } from "./actions";

export default function ContactPage() {
  return (
    <form action={submitContact}>
      <input type="email" name="email" required />
      <button type="submit">Send</button>
    </form>
  );
}

Neither snippet is the full picture — that's exactly the point of this article. Guides is where the full picture for each of these lives; this is just enough to recognize the shape of the problem before you go looking for it.

Key Takeaways

Category	Representative Guides	What They Solve
Data & Caching	How Revalidation Works, ISR (both versions), Caching (Previous Model), CDN Caching, CI Build Caching	Keeping cached content fresh without full rebuilds, and understanding two generations of Next.js's caching model
Auth & Security	Authentication (both versions), Data Security, Content Security Policy	Keeping session checks close to data access, and preventing server-only data or scripts from leaking to the client
Styling	CSS-in-JS, Sass, Tailwind CSS v3, Preventing Flash	Setting up a styling approach and avoiding visual flashes tied to server/client mismatches
Rendering & Navigation	Rendering Philosophy, Prefetching cluster, Preserving UI State, Streaming, View Transitions	Making navigation and rendering feel instant, and animating between states meaningfully
Forms & Interactivity	Forms, Server Actions, Interactive Apps, Offline Support	Wiring up mutations correctly and handling their failure modes gracefully
Performance	Lazy Loading, Package Bundling, Third Party Libraries, Scripts, Videos, Memory Usage	Keeping bundle size and resource usage under control
Architecture	Multi-tenant, Multi-zones, Backend for Frontend	Serving multiple customers, apps, or teams from one deployment strategy
Observability	Debugging, Instrumentation, OpenTelemetry	Diagnosing problems locally and tracing them in production
Deployment	Building, Deploying to Platforms, Self-Hosting, Static Exports, SPAs, PWAs	Choosing and executing a deployment strategy that matches your infrastructure
Migration	Migrating (CRA, Vite, Pages Router), Migrating to Cache Components	Moving an existing codebase onto Next.js or onto its newer caching model
Testing	Testing overview, Cypress, Jest, Playwright, Vitest	Picking and configuring a test runner for your project

The Guides section isn't meant to be read cover to cover — it's meant to be searched, the same way you'd search a large cookbook rather than reading it front to back. Knowing the categories above, and knowing to check your cacheComponents flag before trusting any caching-related guide, should save you the time I spent the first few times I went looking for something specific in there and wasn't sure which of two similarly-named pages actually applied to my project.