Next.js

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the section bibliography.

This section is written against Next.js 16.3 (16.3.8 was the latest release on 2026-10-03, when every version, URL and example in the section was checked, and the official documentation reported @doc-version 16.3.8), React 19.3 (19.3.0), Node.js 20.9 or later and TypeScript 5.1 or later. It describes the App Router as the primary model and the Pages Router wherever an existing application still uses it. Two caching models coexist in 16.3: the previous model (the default) and the opt-in Cache Components model (cacheComponents: true); every page that touches caching says which one each example uses.

Next.js publishes one major version a year and gives each one a long-term support life cycle. On 2026-10-03 the support policy listed Next.js 16.x (released 2025-10-21) as Active LTS — new features, bug fixes and security patches until Next.js 17 ships — and Next.js 15.x (released 2024-10-21) as Maintenance LTS, which receives only critical bug fixes and security updates, as semver-minor releases, for two years from its first release; 14.x and older are unsupported. Patch releases are frequent, and several of them in 2026 were security releases, so pin an exact version and read the release notes before updating. The Release Cadence and Support Policy section and the What’s Changed & Upgrading page cover the details.

What Next.js is

Next.js is an open-source React framework, maintained by Vercel and developed in the open on GitHub, for building full-stack web applications. React describes the user interface as components; Next.js supplies everything around them that a production site needs:

file-system routing: the App Router (app/, recommended) built on React Server Components, with the older Pages Router (pages/) still supported
React Server Components, Client Components and Server Functions (Server Actions)
every rendering strategy — server-side rendering, client-side rendering, static site generation, incremental static regeneration and Partial Prerendering — with streaming and hydration
a multi-layer cache with explicit revalidation APIs
Route Handlers for HTTP APIs, and Proxy (called Middleware before Next.js 16) in front of every request
image, font and script optimisation, and the Metadata API for SEO
Turbopack, the default bundler since Next.js 16, and the React Compiler
deployment to a Node.js server, a Docker container, static hosting, or a platform through an adapter

A new project is one command away:

npx create-next-app@latest bookshelf --yes
cd bookshelf
npm run dev

Source: Installation

Who this section is for

The section is for developers who already know React and want to build and ship React applications with Next.js:

React developers moving from a client-only single-page application (for example a Vite SPA with React Router) to server rendering, static generation and React Server Components
readers of older Next.js books and tutorials, which mostly target the Pages Router and Next.js 12 or 13, who need to know what changed (async request APIs, proxy.ts, Turbopack, the new caching APIs, Auth.js v5)
back-end developers on this site’s FastAPI, NestJS or Django sections who want a front end for the same Bookshelf API, and teams choosing between Next.js and other React or non-React frameworks

It does not re-teach React itself: components, Hooks, Suspense, Actions and the React Compiler are covered in the React Reference, and the pages here link there instead of repeating it.

The Bookshelf scenario

Every example builds one small, original application, Bookshelf: a Next.js App Router front end in the same domain as the Python FastAPI, NestJS and Django sections, so that the stacks can be compared page by page. It extends the Next.js files sketched on NestJS vs Next.js and has:

a public catalogue of books, authors and reviews: statically generated book pages (generateStaticParams with ISR or 'use cache'), a server-rendered search page that reads searchParams, and client-side filters
a personalised header and a "my reviews" area, rendered dynamically from cookies() and streamed with Suspense
review creation and editing with Server Actions, useActionState, useOptimistic and updateTag
an intercepted-route modal for book covers and a parallel-route slot
sign-in with Auth.js v5, a Data Access Layer, and forbidden() / unauthorized()
a JSON API built with Route Handlers, plus a backend-for-frontend variant that proxies the FastAPI, NestJS or Django Bookshelf API
proxy.ts for locale detection (app/[locale]) and an optimistic authentication check
next/image covers, next/font, Tailwind CSS v4, and the Metadata API with Open Graph images, a sitemap and robots.txt
tests with Vitest and Playwright
a Docker standalone deployment, and a static-export variant of the catalogue

Figure 1. The Bookshelf application: clients, the Next.js server and its backing services

The final project layout (app/[locale]/(shop), app/[locale]/(account), @modal, components/, lib/dal.ts, lib/actions/, proxy.ts, instrumentation.ts and next.config.ts) is assembled on Project Structure. Stripe and headless-CMS commerce concepts are covered by a separate worked example on Advanced Patterns.

Reading path

Read the React Reference first if components, props, state, effects, Hooks and Suspense are new; in particular Server Rendering, SSG and React Server Components explains the React primitives that Next.js automates. Then read this section in order the first time, and use it as a reference afterwards:

Foundations: what a React framework adds, a first project, the project structure, and configuration, TypeScript and environment variables.
Routing: the file-system router, layouts and special files, dynamic routes and route groups, linking and navigation, parallel and intercepting routes, redirects, rewrites and Proxy, and internationalisation.
Rendering: the rendering model, Server and Client Components, server-side rendering, streaming, client-side rendering, static site generation, incremental static regeneration, hydration, and Partial Prerendering with Cache Components.
Data: data fetching, Server Actions and mutations, caching, and Route Handlers with the backend-for-frontend pattern.
UI and optimisations: styling, images, fonts and scripts, metadata and SEO, and performance.
Security and authentication: authentication and authorisation, then data security and Content Security Policy.
Tooling, testing and operations: Turbopack and the compiler, testing, and debugging, instrumentation and observability.
Production: deployment and self-hosting, the Pages Router, and what changed and how to upgrade.
Beyond the basics: advanced patterns.

Readers who know Next.js from older books or tutorials can start with What’s Changed & Upgrading and then jump to the topics they use. The React + Next.js Cheat Sheet condenses React and Next.js onto one printable page.

mindmap root((Next.js)) Foundations Introduction and architecture Getting started Project structure Configuration and env vars Routing Routing fundamentals Layouts and special files Dynamic routes and groups Linking and navigation Parallel and intercepting routes Redirects rewrites and Proxy Internationalization Rendering Rendering fundamentals Server and Client Components Server-side rendering Streaming and Suspense Client-side rendering Static site generation Incremental static regeneration Hydration PPR and Cache Components Data Data fetching Server Actions Caching Route Handlers and BFF UI and optimisations Styling Images fonts and scripts Metadata and SEO Performance and Web Vitals Security Authentication and authorization Data security and CSP Tooling and testing Turbopack and the compiler Testing Debugging and observability Production Deployment and self-hosting Pages Router Upgrading Beyond the basics Advanced patterns Cheat sheet

Figure 2. The section at a glance

What’s covered

Each page builds on the Bookshelf scenario, states the versions it was checked against, and ends with the official sources it derives from. The pages marked ★★ — routing, server-side rendering, client-side rendering, static site generation and hydration — are the most detailed.

Foundations

Routing

Rendering

Data

UI and optimisations

Security and authentication

Tooling, testing and operations

Production

Beyond the basics

Where related material lives elsewhere on this site

The Next.js pages link to existing material instead of repeating it, and cover only what Next.js adds.

Topic Where it lives How the Next.js section relates

Topic	Where it lives	How the Next.js section relates
React fundamentals: components, Hooks, Suspense, Actions, the React Compiler, server rendering	React Reference, in particular Server Rendering, SSG and React Server Components, Routing, Getting Started with React, Data Fetching, Forms and Actions, Build and Deployment and Code Splitting and Suspense	The Next.js pages link here for React itself and explain only how Next.js builds on each primitive.
The NestJS comparison and the first Next.js Bookshelf sketch	NestJS vs Next.js and NestJS	The Bookshelf scenario extends the files sketched there (`app/books/page.tsx`, `lib/books-api.ts`, `app/api/books/route.ts`, a Server Action); the Route Handlers & Backend for Frontend page links back to it.
TypeScript and JSX, JavaScript	TypeScript, including JSX and Frameworks, and JavaScript Development	The configuration page links here instead of re-explaining TypeScript or JSX, and shows only the Next.js plugin, typed routes and generated types.
Node.js runtime: modules, the event loop, streams, HTTP, `worker_threads`, deployment	Node.js	Linked for the runtime Next.js runs on; the Next.js pages cover only what Next.js adds.
Server rendering in other stacks	Vue: Server-Side Rendering (Nuxt) and Angular: Production and Performance (`@angular/ssr`, incremental hydration)	The rendering pages compare them in "the same idea in other stacks" notes, and the introduction’s framework table links them.
Styling, HTML and CSS, accessibility, CORS and browser testing	Tailwind CSS, Sass: Compilation, HTML & CSS, Accessibility, CORS and End-to-End Testing in Real Browsers	Linked from the styling, metadata and SEO, Route Handlers and testing pages, which cover only the Next.js side.
OAuth 2.0, OpenID Connect, JWT and the browser-based-app BFF pattern	OAuth Reference, including Browser-Based Apps, OpenID Connect and JWT & JOSE	The authentication page links here for protocol theory and documents Auth.js, which no other page on this site covers.
GraphQL and the Apollo Client SSR cache	GraphQL, including Apollo Client Configuration	The data-fetching page links here and shows only `@apollo/client-integration-nextjs`.
The same Bookshelf API in Python and TypeScript back ends	Python FastAPI (including Static Files, Templates & Frontend), NestJS and Django	The Next.js front end can consume any of them through the backend-for-frontend page.
Architecture: layering front end and back end, choosing a stack	Layering Backend & Frontend and Starting a New Project	The introduction links here for the "SSR hybrid" option and the choice of stack.
Containers, orchestration and cloud hosting	Docker, Kubernetes Reference, AWS: Developer Tools and DevOps (Amplify Hosting), AWS: CloudFront CDN, Azure: App Service and Functions (Static Web Apps) and Google Cloud	The deployment page shows only the Next.js-specific parts (`output: 'standalone'`, static export, adapters, self-hosting caches).
AI chat front ends and AI-assisted prototyping	Conversational Channels and AI-Assisted Development	The advanced-patterns page links here for Next.js chat UIs and AI-generated prototypes.

React fundamentals: components, Hooks, Suspense, Actions, the React Compiler, server rendering

React Reference, in particular Server Rendering, SSG and React Server Components, Routing, Getting Started with React, Data Fetching, Forms and Actions, Build and Deployment and Code Splitting and Suspense

The Next.js pages link here for React itself and explain only how Next.js builds on each primitive.

The NestJS comparison and the first Next.js Bookshelf sketch

NestJS vs Next.js and NestJS

The Bookshelf scenario extends the files sketched there (app/books/page.tsx, lib/books-api.ts, app/api/books/route.ts, a Server Action); the Route Handlers & Backend for Frontend page links back to it.

TypeScript and JSX, JavaScript

TypeScript, including JSX and Frameworks, and JavaScript Development

The configuration page links here instead of re-explaining TypeScript or JSX, and shows only the Next.js plugin, typed routes and generated types.

Node.js runtime: modules, the event loop, streams, HTTP, worker_threads, deployment

Node.js

Linked for the runtime Next.js runs on; the Next.js pages cover only what Next.js adds.

Server rendering in other stacks

Vue: Server-Side Rendering (Nuxt) and Angular: Production and Performance (@angular/ssr, incremental hydration)

The rendering pages compare them in "the same idea in other stacks" notes, and the introduction’s framework table links them.

Styling, HTML and CSS, accessibility, CORS and browser testing

Tailwind CSS, Sass: Compilation, HTML & CSS, Accessibility, CORS and End-to-End Testing in Real Browsers

Linked from the styling, metadata and SEO, Route Handlers and testing pages, which cover only the Next.js side.

OAuth 2.0, OpenID Connect, JWT and the browser-based-app BFF pattern

OAuth Reference, including Browser-Based Apps, OpenID Connect and JWT & JOSE

The authentication page links here for protocol theory and documents Auth.js, which no other page on this site covers.

GraphQL and the Apollo Client SSR cache

GraphQL, including Apollo Client Configuration

The data-fetching page links here and shows only @apollo/client-integration-nextjs.

The same Bookshelf API in Python and TypeScript back ends

Python FastAPI (including Static Files, Templates & Frontend), NestJS and Django

The Next.js front end can consume any of them through the backend-for-frontend page.

Architecture: layering front end and back end, choosing a stack

Layering Backend & Frontend and Starting a New Project

The introduction links here for the "SSR hybrid" option and the choice of stack.

Containers, orchestration and cloud hosting

Docker, Kubernetes Reference, AWS: Developer Tools and DevOps (Amplify Hosting), AWS: CloudFront CDN, Azure: App Service and Functions (Static Web Apps) and Google Cloud

The deployment page shows only the Next.js-specific parts (output: 'standalone', static export, adapters, self-hosting caches).

AI chat front ends and AI-assisted prototyping

Conversational Channels and AI-Assisted Development

The advanced-patterns page links here for Next.js chat UIs and AI-generated prototypes.

Related topics that are planned but not yet part of this site are mentioned in prose only, where relevant: a programming languages comparison (issue #196), a cloud providers comparison for hosting choices (#201), API managers, secret managers, gateways and scaling (#184), e-commerce platforms (#246) and documentation tools such as the React-based Docusaurus (#247).

Bibliography

Every source used to prepare this section is listed here, each linked to its official site. Individual pages list the subset they derive from under their own == References heading.

Books

Both books target the Pages Router on Next.js versions that are no longer supported (12 and 13.2, with React 17 and 18). They were consulted for concept coverage, narrative and structure only; no text, code listing, figure or sample project is taken from them, every example in this section is written against the current official documentation, and the pages point out where the books are outdated.

Riva, M. Real-World Next.js: Build scalable, high-performance, and modern web applications using Next.js, the React framework for production, 1st ed. Packt Publishing, January 2022. ISBN 978-1-80107-349-3. Covers Next.js 12 and React 17 with the Pages Router. Packt publisher page; companion code: PacktPublishing/Real-World-Next.js on GitHub.
Libby, A. Practical Next.js for E-Commerce: Create E-Commerce Sites with the Next.js Framework, 1st ed. Apress (Springer Nature), 2023. ISBN 978-1-4842-9611-0 (print), 978-1-4842-9612-7 (eBook), DOI 10.1007/978-1-4842-9612-7. Covers Next.js 13.2 and React 18.2 with the Pages Router. Apress / Springer publisher page; companion code: Apress/Practical-Next.js-for-E-Commerce on GitHub.

Official Next.js documentation and resources

Published at nextjs.org/docs (the machine-readable index is llms.txt, @doc-version 16.3.8 on 2026-10-03), grouped as the documentation is:

App Router:
- Getting Started
- Guides
- API Reference: Directives, Components, File-system conventions, Functions, next.config.js options, TypeScript, ESLint, CLI, Edge Runtime, Turbopack and Adapters
- Glossary
Pages Router (with its own index, llms.txt)
Architecture and Community
Error messages, one page per code under nextjs.org/docs/messages/, for example react-hydration-error and blocking-prerender-dynamic; their sources live in the errors folder of the Next.js repository
Upgrade guides: version 14, version 15, version 16 and Codemods
The Next.js blog, in particular the release posts Next.js 15, Next.js 15.5, Next.js 16, Next.js 16.1, Next.js 16.2, Next.js 16.3 and Next.js 16.3: Instant Navigations, and the security posts September 2026 Security Release and Security Update for a Critical Upstream Issue
Support policy and the Learn course
The source code and examples, vercel/next.js on GitHub, and the next package on npm

Official React documentation

Published at react.dev:

Server Components, Server Functions and directives: Server Components, Server Functions, 'use client' and 'use server'
react-dom/client: hydrateRoot
react-dom/server and react-dom/static: renderToReadableStream, renderToPipeableStream, resume, prerender and resumeAndPrerender
Suspense, lazy, use, cache, Activity, ViewTransition and browser()
Actions: useActionState, useFormStatus and useOptimistic
The React Compiler: Introduction and Incremental Adoption
Starting a project: Creating a React App and Build a React App from Scratch
The React blog: React 19, React 19.2, React 19.3 and React Compiler 1.0

The books are consulted references for concept coverage, narrative and structure; they are not reproduced here. The official documentation linked above is authoritative, and where the two differ, the documentation of the version you run prevails.