# Code Reference β Next.js
_14 pages_
---
# Next.js (/docs/nextjs)
# Next.js [#nextjs]
App Router, RSC, deployment.
Browse the sidebar for every cheat sheet in this section.
## Sections [#sections]
*All notes are listed in the sidebar.*
---
# App Router (/docs/nextjs/app-router)
# App Router [#app-router]
*Next.js Β· Reference cheat sheet*
***
## π Overview [#-overview]
The App Router uses the `app/` directory for routes, layouts, loading UI, and nested segments. Folders define URL segments; special files define UI and behavior.
## π§ Core concepts [#-core-concepts]
| File | Role |
| --------------- | -------------------------------------------------------- |
| `page.tsx` | UI for a route (required for that URL) |
| `layout.tsx` | Shared UI wrapping children; persists across navigations |
| `loading.tsx` | Instant loading UI (Suspense boundary) |
| `error.tsx` | Error boundary for the segment |
| `not-found.tsx` | 404 UI |
| `route.ts` | Route Handler (API endpoint) |
| `template.tsx` | Like layout but remounts on navigation |
| `default.tsx` | Fallback for parallel routes |
| Convention | Meaning |
| ------------- | ---------------------------- |
| `[id]` | Dynamic segment |
| `[...slug]` | Catch-all |
| `[[...slug]]` | Optional catch-all |
| `(group)` | Route group β no URL segment |
| `@slot` | Parallel route slot |
## π‘ Examples [#-examples]
**Nested layout:**
```
app/
layout.tsx
page.tsx β /
blog/
layout.tsx
page.tsx β /blog
[slug]/
page.tsx β /blog/:slug
```
**Dynamic page:**
```tsx
// app/blog/[slug]/page.tsx
export default async function Post({
params,
}: {
params: Promise<{ slug: string }>;
}) {
const { slug } = await params;
return
{slug}
;
}
```
**Route group (no URL impact):**
```
app/(marketing)/about/page.tsx β /about
app/(shop)/cart/page.tsx β /cart
```
## β οΈ Pitfalls [#οΈ-pitfalls]
* `layout.tsx` does not remount on soft navigation β don't put one-shot client state there expecting reset.
* `params` and `searchParams` are async in recent Next.js β await them.
* A folder without `page.tsx` is not a reachable route by itself.
## π Related [#-related]
* [pages\_router.md](/docs/nextjs/pages-router)
* [server\_components.md](/docs/nextjs/server-components)
* [route\_handlers.md](/docs/nextjs/route-handlers)
* [link\_navigation.md](/docs/nextjs/link-navigation)
* [getting\_started.md](/docs/nextjs/getting-started)
---
# Caching (/docs/nextjs/caching)
# Caching [#caching]
*Next.js Β· Reference cheat sheet*
***
## π Overview [#-overview]
App Router caching spans the Request Memoization, Data Cache, Full Route Cache, and Router Cache. Defaults favor static where possible; opt into dynamic when data must be fresh.
## π§ Core concepts [#-core-concepts]
| Cache | What it stores |
| ------------------- | --------------------------------------------- |
| Request Memoization | Dedupes identical `fetch` in one render pass |
| Data Cache | Persistent server fetch cache across requests |
| Full Route Cache | Pre-rendered HTML/RSC payload at build |
| Router Cache | Client-side cache of visited segments |
| Control | Effect |
| --------------------------------------------- | ------------------------------------ |
| `fetch(url, \{ cache: 'no-store' \})` | Skip Data Cache |
| `fetch(url, \{ next: \{ revalidate: N \} \})` | ISR-style revalidate every N seconds |
| `revalidatePath` / `revalidateTag` | On-demand invalidation |
| `export const dynamic = 'force-dynamic'` | Always dynamic route |
| `export const revalidate = 60` | Segment revalidate window |
## π‘ Examples [#-examples]
**Time-based revalidation:**
```ts
const res = await fetch("https://api.example.com/items", {
next: { revalidate: 3600, tags: ["items"] },
});
```
**On-demand revalidate (Server Action / Route Handler):**
```ts
import { revalidateTag } from "next/cache";
export async function refreshItems() {
revalidateTag("items");
}
```
**Force dynamic:**
```ts
export const dynamic = "force-dynamic";
```
## β οΈ Pitfalls [#οΈ-pitfalls]
* Stale UI after mutations usually means missing `revalidatePath`/`revalidateTag`.
* Caching behavior differs between local `next dev` and production builds.
* Mixing `no-store` fetches inside otherwise static layouts can turn the whole route dynamic.
## π Related [#-related]
* [server\_components.md](/docs/nextjs/server-components)
* [route\_handlers.md](/docs/nextjs/route-handlers)
* [deployment.md](/docs/nextjs/deployment)
* [app\_router.md](/docs/nextjs/app-router)
---
# Deployment (/docs/nextjs/deployment)
# Deployment [#deployment]
*Next.js Β· Reference cheat sheet*
***
## π Overview [#-overview]
Deploy Next.js with a Node server (`next start`), a Platform-as-a-Service (Vercel, etc.), or a static export when the app has no server-only features.
## π§ Core concepts [#-core-concepts]
| Mode | Command / config | Fits |
| ------------- | --------------------------- | ------------------------ |
| Node server | `next build` β `next start` | SSR, Route Handlers, ISR |
| Vercel | Git integration | Full Next.js feature set |
| Docker | Multi-stage Node image | Self-hosted |
| Static export | `output: 'export'` | Fully static sites only |
| Checklist | Why |
| ----------------------- | ------------------------------ |
| Set production env vars | Secrets and `NEXT_PUBLIC_*` |
| `NODE_ENV=production` | Optimizations |
| Health endpoint | Orchestrators / load balancers |
| Match Node version | Avoid native module mismatches |
## π‘ Examples [#-examples]
**Build & start:**
```shellscript
npm run build
npm run start
```
**Static export (`next.config.ts`):**
```ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
output: "export",
};
export default nextConfig;
```
**Docker (sketch):**
```dockerfile
FROM node:22-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci
FROM node:22-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build
FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json
EXPOSE 3000
CMD ["npm", "start"]
```
## β οΈ Pitfalls [#οΈ-pitfalls]
* Static export cannot use server features (SSR cookies, many Route Handlers, ISR the same way).
* Forgetting to set env vars on the host causes runtime crashes that never appeared locally.
* Binding only to `localhost` inside containers breaks external access β listen on `0.0.0.0` when required by the host.
## π Related [#-related]
* [env.md](/docs/nextjs/env)
* [caching.md](/docs/nextjs/caching)
* [middleware.md](/docs/nextjs/middleware)
* [getting\_started.md](/docs/nextjs/getting-started)
* [Docker/getting\_started.md](/docs/nextjs/../docker/getting-started)
---
# Environment Variables (/docs/nextjs/env)
# Environment Variables [#environment-variables]
*Next.js Β· Reference cheat sheet*
***
## π Overview [#-overview]
Next.js loads `.env*` files and exposes variables to Node (server) and, with a prefix, to the browser bundle. Never ship secrets with the public prefix.
## π§ Core concepts [#-core-concepts]
| File | Typical use |
| -------------------------------------- | ----------------------------------- |
| `.env` | Default for all environments |
| `.env.local` | Local secrets (gitignored) |
| `.env.development` / `.env.production` | Env-specific defaults |
| `.env*.local` | Overrides; highest priority locally |
| Access | Visibility |
| ---------------------------------- | ------------------------------------------ |
| `process.env.MY_SECRET` | Server only |
| `process.env.NEXT_PUBLIC_*` | Inlined into client JS |
| `NEXT_PUBLIC_*` in Edge/Middleware | Available if set at build/runtime per host |
## π‘ Examples [#-examples]
**`.env.local`:**
```shellscript
DATABASE_URL=postgres://...
NEXT_PUBLIC_APP_URL=http://localhost:3000
```
**Server usage:**
```ts
const url = process.env.DATABASE_URL;
if (!url) throw new Error("DATABASE_URL is required");
```
**Client usage:**
```tsx
"use client";
export function Banner() {
return
{process.env.NEXT_PUBLIC_APP_URL}
;
}
```
## β οΈ Pitfalls [#οΈ-pitfalls]
* Changing env vars often requires restarting `next dev` / rebuilding.
* `NEXT_PUBLIC_` values are baked in at build time for many hosts β treat them as public.
* Don't put API keys in `NEXT_PUBLIC_*` even "temporarily".
## π Related [#-related]
* [server\_components.md](/docs/nextjs/server-components)
* [deployment.md](/docs/nextjs/deployment)
* [middleware.md](/docs/nextjs/middleware)
* [caching.md](/docs/nextjs/caching)
---
# Getting Started with Next.js (/docs/nextjs/getting-started)
# Getting Started with Next.js [#getting-started-with-nextjs]
*Next.js Β· Reference cheat sheet*
***
## π Overview [#-overview]
Next.js is a React framework for full-stack web apps. It adds routing, rendering modes, image optimization, and deployment conventions on top of React.
## π§ Core concepts [#-core-concepts]
| Idea | Meaning |
| ------------ | ----------------------------------------------------- |
| App Router | File-based routing under `app/` (default in new apps) |
| Pages Router | Legacy file-based routing under `pages/` |
| RSC | React Server Components β default in App Router |
| SSR / SSG | Server-render on request vs pre-render at build |
| Turbopack | Fast bundler used by `next dev` (newer versions) |
**Create a project:**
```shellscript
npx create-next-app@latest my-app
cd my-app
npm run dev
```
| Script | Purpose |
| ------------ | ------------------------ |
| `next dev` | Local development server |
| `next build` | Production build |
| `next start` | Serve production build |
| `next lint` | Run ESLint |
## π‘ Examples [#-examples]
**Minimal `app/page.tsx`:**
```tsx
export default function Home() {
return
Hello Next.js
;
}
```
**`package.json` scripts:**
```json
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start"
}
}
```
**Check version:**
```shellscript
npx next --version
```
## β οΈ Pitfalls [#οΈ-pitfalls]
* Mixing App Router (`app/`) and Pages Router (`pages/`) without a clear plan causes confusion.
* Client hooks (`useState`, `useEffect`) need `'use client'` in App Router.
* Forgetting `next build` before `next start` serves a stale or missing build.
## π Related [#-related]
* [app\_router.md](/docs/nextjs/app-router)
* [pages\_router.md](/docs/nextjs/pages-router)
* [server\_components.md](/docs/nextjs/server-components)
* [deployment.md](/docs/nextjs/deployment)
* [glossary.md](/docs/nextjs/glossary)
---
# Glossary (/docs/nextjs/glossary)
# Glossary [#glossary]
*Next.js Β· Reference cheat sheet*
***
## π Overview [#-overview]
Alphabetical glossary of Next.js terms spanning App Router, rendering, caching, and deployment.
## π§ Core concepts [#-core-concepts]
| Term | Definition |
| -------------------- | ------------------------------------------------------------------- |
| App Router | Routing system based on the `app/` directory and special files. |
| CSR | Client-side rendering in the browser after JS loads. |
| Dynamic segment | Folder like `[id]` that captures a URL parameter. |
| Edge runtime | Lightweight runtime for Middleware and some Route Handlers. |
| Hydration | Attaching client React to server-rendered HTML. |
| ISR | Incremental Static Regeneration β update static pages after deploy. |
| Layout | Persistent UI wrapper (`layout.tsx`) shared by child routes. |
| Middleware | Edge code that runs before a request is completed. |
| Partial Prerendering | Hybrid static shell + dynamic holes (version-dependent). |
| Prefetch | Loading a route in the background via `Link`. |
| Route Handler | `route.ts` exporting HTTP methods as an API endpoint. |
| Route group | `(name)` folder that organizes routes without affecting the URL. |
| RSC | React Server Component rendered on the server by default. |
| Soft navigation | Client transition without full document reload. |
| SSG | Static Site Generation at build time. |
| SSR | Server-Side Rendering on each request. |
| Streaming | Sending UI in chunks via Suspense / `loading.tsx`. |
| Turbopack | Rust-based bundler used in modern `next dev`. |
## π‘ Examples [#-examples]
**Dynamic segment mental model:**
```
app/shop/[slug]/page.tsx β /shop/shoes
```
**RSC vs client:**
```tsx
// Server (default)
export default async function Page() { /* fetch, await */ }
// Client
"use client";
export function Widget() { /* useState, onClick */ }
```
## β οΈ Pitfalls [#οΈ-pitfalls]
* Glossaries drift β verify behavior against your installed Next.js major version.
* βStaticβ vs βdynamicβ depends on APIs used (`cookies`, `headers`, `no-store`), not folder names alone.
## π Related [#-related]
* [getting\_started.md](/docs/nextjs/getting-started)
* [app\_router.md](/docs/nextjs/app-router)
* [caching.md](/docs/nextjs/caching)
* [server\_components.md](/docs/nextjs/server-components)
* [README.md](/docs/nextjs)
---
# next/image (/docs/nextjs/image)
# next/image [#nextimage]
*Next.js Β· Reference cheat sheet*
***
## π Overview [#-overview]
`next/image` optimizes images: resizing, modern formats, lazy loading, and layout shift prevention via required dimensions or `fill`.
## π§ Core concepts [#-core-concepts]
| Prop | Purpose |
| ------------------ | ----------------------------------------------- |
| `src` | Path or remote URL |
| `alt` | Required accessibility text |
| `width` / `height` | Intrinsic size (static imports can infer) |
| `fill` | Fill parent (parent needs `position: relative`) |
| `sizes` | Hint for responsive `srcset` |
| `priority` | Preload above-the-fold images |
| `placeholder` | `"blur"` or `"empty"` |
| Config (`next.config`) | Purpose |
| ----------------------------------- | --------------------- |
| `images.remotePatterns` | Allow remote hosts |
| `images.formats` | AVIF/WebP preferences |
| `images.deviceSizes` / `imageSizes` | Generated widths |
## π‘ Examples [#-examples]
**Local image:**
```tsx
import Image from "next/image";
import hero from "@/public/hero.jpg";
export function Hero() {
return ;
}
```
**Remote with sizes:**
```tsx
```
**Fill layout:**
```tsx