Next.js 16 Essentials

# Overview

Here are the main updates in Next.js 16.

• Caching (important)
  • Supports Partial Prerendering (PPR), which caches pages, components, and functions with the 'use cache' directive.
  • revalidateTag() now requires a cache profile.
  • New caching APIs have been added.
    • updateTag(): Expires the cache for the given tag and fetches fresh data.
    • refresh(): Refreshes only uncached data and doesn't affect the cache at all.
• Middleware file renamed (important)
  • middleware.ts has been renamed to proxy.ts.
• Async request APIs enforced (important)
  • The async APIs introduced in Next.js 15 are now fully enforced.
  • params, searchParams, cookies(), headers(), and others can only be accessed asynchronously.
• Stable React Compiler support (important)
  • React Compiler, which provides automatic memoization, is now stable.
  • Using React Compiler is highly recommended.
• Next.js DevTools MCP (important)
  • Supports an AI MCP for features such as Next.js knowledge, unified logs, automatic error checking, and page awareness.
  • Better access to up-to-date information is expected to greatly reduce problems caused by outdated information.
• Turbopack by default
  • Turbopack is now stable and has replaced Webpack as the default bundler.
  • If needed, you can opt out with the --webpack flag.
• React 19.2 support
  • You can use the latest React features, such as useEffectEvent() and <Activity/>.
• Parallel routes require a default
  • Every parallel route slot needs an explicit default component.
• Improved logging
  • Development logs show how long the build process, compilation, rendering, and so on take.
• Improved prefetch performance
  • When prefetching several URLs that share a layout, the layout is downloaded only once.
  • Only the needed parts are prefetched, excluding parts that are already cached.
• Image configuration defaults changed
  • The default values of options in the images configuration, such as minimumCacheTTL, qualities, and maximumRedirects, have changed.
• ESLint Flat Config by default
  • ESLint v10 drops support for legacy configuration, and the ESLint Flat Config format is used by default for faster linting and easier management.
• Improved development performance
  • The Turbopack file system cache became the default for next dev in v16.1 and then for next build in v16.3, so compilation results are reused from disk.
  • After a development server restart, the first compilation is 5-14x faster, and repeated builds are up to 5.5x faster.
  • In v16.2, the startup time of next dev was cut by about 87%, and in v16.3, memory eviction became the default, reducing the memory usage of long-running development servers by up to 90%.
• Improved runtime performance
  • In v16.2, deserialization of Server Component payloads was improved, making HTML rendering 25-60% faster.
  • In v16.3, the App Router's rendering layer was replaced with native Node.js streams, increasing request throughput under load by up to 22%.

Here are the main updates in Next.js 15.

• Automated upgrade CLI (@next/codemod)
  • A CLI is provided to make upgrading your Next.js version easy.
  • You can upgrade with the npx @next/codemod@canary upgrade latest command.
  • It doesn't handle detailed code changes, so you still need to check things yourself.
• Async request APIs (important)
  • Next.js changed to handle components that don't need data requests asynchronously, which speeds up the initial load.
  • Key APIs such as params and searchParams switched to async usage.
• Caching defaults changed (important)
  • Default caching for GET requests and client navigation has been turned off.
  • This is nice because it doesn't overlap with the caching features of libraries like TanStack Query.
  • You can turn caching back on with the cache: 'force-cache' option.
• React 19 support (important)
  • Supports React 19 compatibility while keeping partial backward compatibility with React 18.
• <Form> component
  • An optimized component that extends the <form> element; it prefetches the submission route and preserves submitted data as a query string.
• Turbopack Dev stable
  • next dev --turbo mode is now stable, providing a faster development environment and quicker responses.
• Static route indicator
  • During development, a marker in the bottom corner of the screen shows whether a route is prerendered (⚡ Static route).
• API for running code after async work (unstable_after)
  • A new API that lets you handle additional work asynchronously after streaming finishes.
  • It isn't stable yet, so it's best to treat it as a reference only.
• /instrumentation.js API stable
  • You can observe the server lifecycle to monitor performance and track errors.
• TypeScript configuration support
  • Config files written in TypeScript are supported, with autocompletion and type safety.
• Improved self-hosting
  • You get more control over cache control headers, and image optimization performance has improved.
• Stronger security
  • Security has been strengthened with features that prevent Server Actions from becoming public endpoints.
• Optimized bundling of external packages
  • A configuration option for bundling external packages has been added.
• ESLint 9 support
  • Supports ESLint 9 to reflect the latest rules and maintain compatibility.
• Improved build and development performance
  • Static page generation has been optimized, and HMR for Server Components has been enhanced.

# What is Next.js?

Next.js is a React framework developed by Vercel that provides a variety of optimization features, such as server-side rendering (SSR), client-side rendering (CSR), and API routing.
With Next.js, you can extend the core features of React to build web applications faster and more reliably.

# Installation and setup

Create a Next.js project with the following command.
Answer each question with Yes or No.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
npx create-next-app@latest project-name

  ## v16
  ✔ Would you like to use the recommended Next.js defaults? › No, customize settings
  ✔ Would you like to use TypeScript? … No / Yes  # Whether to use TypeScript
  ✔ Which linter would you like to use? › ESLint  # Choose from ESLint / Biome / None
  ✔ Would you like to use React Compiler? … No / Yes  # Whether to use React Compiler
  ✔ Would you like to use Tailwind CSS? … No / Yes  # Whether to use Tailwind CSS
  ✔ Would you like your code inside a `src/` directory? … No / Yes  # Whether to use the src/ directory
  ✔ Would you like to use App Router? (recommended) … No / Yes  # Whether to use App Router
  ✔ Would you like to customize the import alias (`@/*` by default)? … No / Yes  # Whether to use a path alias other than `@/*`
  ✔ Would you like to include AGENTS.md to guide coding agents to write up-to-date Next.js code? … No / Yes  # Whether to include AGENTS.md

  ## v15
  ✔ Would you like to use TypeScript? … Yes  # Whether to use TypeScript
  ✔ Would you like to use ESLint? … Yes  # Whether to use ESLint
  ✔ Would you like to use Tailwind CSS? … Yes  # Whether to use Tailwind CSS
  ✔ Would you like your code inside a `src/` directory? … No  # Whether to use the src/ directory
  ✔ Would you like to use App Router? (recommended) … Yes  # Whether to use App Router
  ✔ Would you like to customize the import alias (@/* by default)? … No  # Whether to use a path alias other than `@/*`

# Prettier

The following VS Code extensions must be installed.

• ESLint: Checks code quality and detects bugs and anti-patterns
• Prettier - Code formatter: Manages code style and formatting, so you can apply a consistent code style

Install the Prettier-related packages.

1
npm i -D prettier eslint-config-prettier eslint-plugin-prettier prettier-plugin-tailwindcss

Update the ESLint configuration as follows.

1
2
3
4
5
6
7
import prettierRecommended from 'eslint-config-prettier'

const eslintConfig = defineConfig([
  { extends: [prettierRecommended] }
])

export default eslintConfig

Also, create a .prettierrc file in the project root and add the rules you want, like this.
You can find the detailed rules in Prettier / Options.

1
2
3
4
5
6
7
8
9
10
{
  "semi": false,
  "singleQuote": true,
  "singleAttributePerLine": true,
  "bracketSameLine": true,
  "endOfLine": "lf",
  "trailingComma": "none",
  "arrowParens": "avoid",
  "plugins": ["prettier-plugin-tailwindcss"]
}

# Auto-formatting settings

You can create the .vscode/settings.json folder and file in the project root and add the following content.

1
2
3
4
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

# Using skills

If you use the Skills feature in AI coding tools such as Claude Code and Cursor, you can install and configure everything automatically and more easily through conversation.
Install the skill with the following command.

1
npx skills add ParkYoungWoong/skills --skill react-next-scaffold

After installation, when you start a Next.js project in your AI coding tool, the skill activates automatically and creates a project that includes the setup above (ESLint, Prettier, path aliases, and so on).
Or you can invoke the skill manually in each tool, as in the following Claude Code example.

1
❯ /react-next-scaffold

# AGENTS.md

AI coding agents write code based on the data they were trained on, so they sometimes use Next.js APIs that no longer exist.
To prevent this, starting with Next.js 16.2, documentation that matches the installed version is included in the package.
The documentation is in the node_modules/next/dist/docs/ path, so agents can read it right away without network requests.

And starting with 16.3, when you run next dev and an AI coding agent is detected in the environment, Next.js creates and maintains AGENTS.md and CLAUDE.md files in the project root.
AGENTS.md contains a managed block like the following, which tells agents to read the bundled documentation before writing code.

1
2
3
4
5
6
7
<!-- BEGIN:nextjs-agent-rules -->

# This is NOT the Next.js you know

<!-- Omitted.. instructions to read the docs for the installed version first -->

<!-- END:nextjs-agent-rules -->

Write your own project instructions outside the area marked by BEGIN and END.
When Next.js updates the managed block, the content outside it stays as it is.

When you start a new project with create-next-app, both files are created automatically, and you can exclude them with the --no-agents-md option.
If you want to turn off automatic creation in an existing project, add the configuration option (agentRules) as follows.

1
2
3
4
5
6
7
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  agentRules: false
}

export default nextConfig

# Dev Indicator

When you run the development server (next dev), the Dev Indicator, shaped like the Next.js logo, appears in the lower left of the browser screen.
It shows things like whether the current route is static (prerendered) or dynamic (rendered on request), and it works only in the development environment.

Next.js Dev Indicator

If it gets in the way by covering the screen, you can hide it by setting the devIndicators option to false, as follows.
This only hides the indicator, so compile and runtime errors still appear on screen as before.

1
2
3
4
5
6
7
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  devIndicators: false
}

export default nextConfig

If you want to move it instead of hiding it, specify something like devIndicators: { position: 'bottom-right' }.
You can choose from 'bottom-left' (default), 'bottom-right', 'top-left', and 'top-right'.
The appIsrStatus, buildActivity, and buildActivityPosition options were removed in v16.

# Server vs Client

In Next.js, you can distinguish between Server Components and Client Components so that parts of your code are rendered on the server or on the client.
By default, every component you create is a Server Component!
To make a component a Client Component, you need the 'use client' declaration at the very top of the component, as follows; without it, the component is a Server Component.

1
2
3
4
5
'use client'

export default function Component() {
  return <></>
}

Server Components and Client Components differ in some of the APIs they can use, as follows.
Thanks to this distinction, Server Components give you benefits such as security, caching, performance, and SEO, while Client Components give you benefits such as interactivity ('click' and 'load' events, and so on) and access to browser APIs (window, document, and so on).

Server Components only:

• cookies
• headers
• redirect
• generateMetadata
• revalidatePath
• ...

Client Components only:

• useState
• useEffect
• onClick
• onChange
• useRouter
• useParams
• useSearchParams
• useFormState
• useOptimistic
• ...

If you use an API that doesn't match the type of component, an error appears right away, as in the following image, so you can quickly tell them apart.

"Error: 'next/headers' only works in Server Components, but it is being used in a Client Component."

# Routing

To use routing, you need to understand Next.js file conventions.
The basic files in the table below form a hierarchy in order starting from layout, and you use each one for its role to render each page.
These explicit file conventions help you keep your project structure clear.

Explicit component hierarchy

# Pages

Next.js uses a file-system-based router that defines routes with folders, so each folder you create inside the /app folder represents a URL path by default.
For example, if you create an /app/movies folder in your project, you can access it at the /movies path, that is, http://localhost:3000/movies.
And the content to render at that path is written in each folder's page.tsx component by default.

Each route part mapped this way is called a segment.

Understanding segments

1
2
3
4
├─app/
│  ├─movies/
│  │  └─page.tsx
│  └─page.tsx

1
2
3
export default function Home() {
  return <h1>Home page!</h1>
}

1
2
3
4
5
6
7
8
9
10
11
12
export default function Movies() {
  return (
    <>
      <h1>Movies page!</h1>
      <ul>
        <li>Avengers</li>
        <li>Avatar</li>
        <li>Frozen</li>
      </ul>
    </>
  )
}

Also, files whose names don't match the routing file conventions above aren't defined as routes, so you can freely add them in the same folder.
In the following image, all files except page.js and route.js aren't defined as routes (Not Routable).

Colocating routing files and folders

# Layouts

UI shared by several child routes is written in the layout.tsx component of each routing folder.
It uses the children prop as a slot, and the page.tsx component at the same level is rendered in place of {children}.
Layouts can also be nested.

1
2
3
4
5
6
7
8
├─app/
│  ├─movies/
│  │  ├─layout.tsx
│  │  └─page.tsx
│  ├─layout.tsx
│  └─page.tsx
├─components/
│  └─Header.tsx

The /app/page.tsx component is rendered in place of {children} in the following code.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import './globals.css'
import Header from '@/components/Header'

export default function RootLayout({
  children
}: Readonly<{
  children: React.ReactNode
}>) {
  return (
    <html lang="ko">
      <body className="antialiased">
        <Header />
        <main className="p-2">{children}</main>
      </body>
    </html>
  )
}

The /app/movies/page.tsx component is rendered in place of {children} in the following code.

1
2
3
4
5
export default function MoviesLayout({
  children
}: Readonly<{ children: React.ReactNode }>) {
  return <section>{children}</section>
}

# Component-based navigation

In Next.js, you use the <Link> component instead of the <a> tag to move between pages.
The <Link> component provides page navigation optimized for Next.js projects, such as loading only part of the optimized bundle without reloading the whole page and supporting server rendering.
Let's add links to each page in the /components/Header.tsx component we saw above.

1
2
3
4
5
6
7
8
├─app/
│  ├─movies/
│  │  ├─layout.tsx
│  │  └─page.tsx
│  ├─layout.tsx
│  └─page.tsx
├─components/
│  └─Header.tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import Link from 'next/link'

export default function Header() {
  return (
    <header>
      <nav className="flex">
        {links.map(({ href, label }) => (
          <Link
            key={href}
            href={href}
            className="px-2">
            {label}
          </Link>
        ))}
      </nav>
    </header>
  )
}

You can use the usePathname hook to compare the current path it returns (pathname) with the path of each <Link> component and add an active style to the current page.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
'use client'
import { usePathname } from 'next/navigation'
import Link from 'next/link'

const links = [
  { href: '/', label: 'Home' },
  { href: '/movies', label: 'Movies' }
]

export default function Header() {
  const pathname = usePathname()
  return (
    <header>
      <nav className="flex">
        {links.map(({ href, label }) => (
          <Link
            key={href}
            href={href}
            className={`px-2 ${pathname === href ? 'bg-blue-600 text-white' : ''} `}>
            {label}
          </Link>
        ))}
      </nav>
    </header>
  )
}

# Prefetching

With the prefetch option, the <Link /> component can fetch the data of the linked route (href) in advance when it appears in the viewport, which greatly improves navigation performance.

• null (default): For static routes, prefetches all child routes; for dynamic routes, prefetches only up to the nearest segment that has loading.tsx.
• true: Prefetches both static and dynamic routes.
• false: Doesn't prefetch.

1
2
3
4
5
6
7
8
9
export default function Links() {
  return (
    <>
      <Link href={someLink}>null</Link>
      <Link prefetch={true} href={someLink}>true</Link>
      <Link prefetch={false} href={someLink}>false</Link>
    </>
  )
}

v16 sends prefetch requests separately for each segment of the route tree.
Shared layouts are received once and reused across routes, which improves cache efficiency, but the number of requests per link increases.

Starting with v16.3, bundling responses below a certain size into one request is the default behavior, so the number of requests went down again.
Large shared segments that can be reused across routes are still kept separate, so cache efficiency is maintained.
There's no code you need to change, but if needed, you can adjust the behavior with the prefetchInlining option.
If you set it to false, responses aren't bundled, and a separate request is sent for each segment.

1
2
3
4
5
6
7
8
9
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    prefetchInlining: false // Default: true
  }
}

export default nextConfig

# Programmatic navigation

Depending on the situation, you sometimes need to navigate programmatically instead of using the <Link> component.
In that case, you can implement navigation with the useRouter hook provided by Next.js, as follows.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
'use client'
import { usePathname } from 'next/navigation'
import { useRouter } from 'next/navigation'
import Link from 'next/link'

const links = [
  { href: '/', label: 'Home' },
  { href: '/movies', label: 'Movies' }
]

export default function Header() {
  const pathname = usePathname()
  const router = useRouter()
  return (
    <header className="flex items-center">
      <nav className="flex">
        {links.map(({ href, label }) => (
          <Link
            key={href}
            href={href}
            className={`px-2 ${pathname === href ? 'bg-blue-600 text-white' : ''} `}>
            {label}
          </Link>
        ))}
      </nav>
      <button
        className="rounded bg-gray-800 px-2 py-1 text-sm text-white transition-colors hover:bg-gray-700"
        onClick={() => router.push('/movies')}>
        Movies(Push)
      </button>
    </header>
  )
}

The router object provides the following methods.

• push(url): Navigate to a page
• replace(url): Navigate to a page (without leaving a history entry)
• back(): Go to the previous page
• forward(): Go to the next page
• refresh(): Refresh the page
• prefetch(url): Prefetch a page

# Prefetching

Unlike the <Link> component, where basic prefetching works automatically, programmatic navigation lets you implement prefetching with the useEffect hook and the router.prefetch() method.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
'use client'
import { useEffect } from 'react'
import { usePathname } from 'next/navigation'
import { useRouter } from 'next/navigation'
import Link from 'next/link'

// Omitted..

export default function Header() {
  const pathname = usePathname()
  const router = useRouter()

  useEffect(() => {
    router.prefetch('/movies')
  }, [router])

  return (
    <header className="flex items-center">
      {/* Omitted.. */}
      <button
        className="rounded bg-gray-800 px-2 py-1 text-sm text-white transition-colors hover:bg-gray-700"
        onClick={() => router.push('/movies')}>
        Movies(Push)
      </button>
    </header>
  )
}

# Dynamic routes

For dynamic routes that can't be defined in advance, write the folder name in square brackets ([]).
Then the URL segment value is passed through the params prop, and the folder name between the brackets becomes the property name.
If you use a query string, it's passed through the searchParams prop.

1
2
3
4
├─app/
│  ├─movies/
│  │  ├─[movieId]/
│  │  │  └─page.tsx

params and searchParams are both Promise objects.
In a Server Component, extract the values you need with the await keyword.

Starting with v16, params, searchParams, cookies(), headers(), and others can no longer be accessed synchronously, and they can only be accessed asynchronously.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
interface Movie {
  Title: string
  Plot: string
}

export default async function MovieDetails({
  params, // Dynamic segment
  searchParams // Query string
}: PageProps<'/movies/[movieId]'>) {
  const { movieId } = await params
  const { plot } = await searchParams
  const res = await fetch(`https://omdbapi.com/?apikey=7035c60c&i=${movieId}&plot=${plot || 'short'}`)
  const movie: Movie = await res.json()
  return (
    <>
      <h1>{movie.Title}</h1>
      <p>{movie.Plot}</p>
    </>
  )
}

PageProps in the example above is a global type generated from your folder structure since v15.5, and you use it by specifying a route string, without importing it.
There are three global types of this kind, and each type accepts only routes that have the corresponding file.

In a Client Component, extract the values you need with the use function.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
'use client'
import { use, useState, useEffect } from 'react'

interface Movie {
  Title: string
  Plot: string
}

export default function MovieDetails({
  params, // Dynamic segment
  searchParams // Query string
}: PageProps<'/movies/[movieId]'>) {
  const { movieId } = use(params)
  const { plot } = use(searchParams)
  const [movie, setMovie] = useState<Movie | null>(null)

  useEffect(() => {
    const fetchMovie = async () => {
      const res = await fetch(`https://omdbapi.com/?apikey=7035c60c&i=${movieId}&plot=${plot || 'short'}`)
      const movie: Movie = await res.json()
      setMovie(movie)
    }
    fetchMovie()
  }, [movieId, plot])

  return (
    <>
      <h1>{movie?.Title}</h1>
      <p>{movie?.Plot}</p>
    </>
  )
}

Let's add a link to a movie details page in the <Header> component.

1
2
3
4
5
6
7
8
9
10
// Omitted..
const links = [
  { href: '/', label: 'Home' },
  { href: '/movies', label: 'Movies' },
  { href: '/movies/tt4154796', label: 'Movie(Avengers)' }
]

export default function Header() {
  // Omitted..
}

Or go to a movie details page by entering the URL directly, like this.

1
2
3
http://localhost:3000/movies/tt4520988?plot=full
http://localhost:3000/movies/tt4154796
http://localhost:3000/movies/tt1630029

As we saw earlier, a [name] folder handles simple dynamic route matching, and you can also use catch-all matching for all child routes ([...name]) or optional catch-all matching ([[...name]]), as in the following examples.

# Loading

While a page is being prepared, you can show a loading state first.
Create a loading.tsx file in the same route (folder) as the page to render.

1
2
3
4
5
├─app/
│  ├─movies/
│  │  ├─[movieId]/
│  │  │  ├─loading.tsx
│  │  │  └─page.tsx

1
2
3
4
5
import Loader from '@/components/Loader'

export default function Loading() {
  return <Loader />
}

To implement an animated loading UI, write the <Loader> component as follows.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
interface LoaderProps {
  size?: number
  weight?: number
  color?: string
  duration?: number
  className?: string
}

export default function Loader({
  size = 40,
  weight = 4,
  color = '#e96900',
  duration = 1,
  className = ''
}: LoaderProps) {
  return (
    <div
      className={`animate-spin rounded-full ${className} `}
      style={{
        width: size,
        height: size,
        borderWidth: weight,
        borderStyle: 'solid',
        borderColor: color,
        borderTopColor: 'transparent',
        animationDuration: `${duration}s`
      }}
    />
  )
}

Write a wait (delay) utility function to add latency.

1
2
3
export default function wait(ms: number) {
  return new Promise(resolve => setTimeout(resolve, ms))
}

As follows, we'll delay fetching the movie details by 2 seconds so that the loading UI is clearly visible.
Now visit the http://localhost:3000/movies/tt4520988 page!

1
2
3
4
5
6
7
8
9
10
11
import wait from '@/utils/wait'

export default async function MovieDetails({
  // Omitted..
}) {
  const { movieId } = await params
  const { plot } = await searchParams
  await wait(2000)
  const res = await fetch(`https://omdbapi.com/?apikey=7035c60c&i=${movieId}&plot=${plot || 'short'}`)
  // Omitted..
}

# Errors

If an error occurs while a page is rendering, you can show an error state.
Create an error.tsx file in the same folder as the page to render.

1
2
3
4
5
6
├─app/
│  ├─movies/
│  │  ├─[movieId]/
│  │  │  ├─error.tsx
│  │  │  ├─loading.tsx
│  │  │  └─page.tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
'use client'
export default function Error({
  error,
  retry
}: {
  error: Error & { digest?: string }
  retry: () => void
}) {
  return (
    <>
      <h2>{error.message}</h2>
      <button onClick={() => retry()}>Try again</button>
    </>
  )
}

retry() became stable in v16.3.
It calls router.refresh() and reset() together inside startTransition(), which fetches the data from the server again and re-renders the segment, so it's recommended for most error recovery situations.

1
2
3
4
5
6
7
8
9
10
import wait from '@/utils/wait'

export default async function MovieDetails({
  // Omitted..
}) {
  // Omitted..
  await wait(2000)
  throw new Error('Something went wrong..')
  // Omitted..
}

# Not found pages

If someone visits a route that isn't defined in your project, you can render a separate page with the not-found.tsx file.

1
2
├─app/
│  └─not-found.tsx

1
2
3
4
5
6
7
8
9
10
import Link from 'next/link'

export default function NotFound() {
  return (
    <>
      <h1 className="text-2xl font-bold">404, page not found.</h1>
      <Link href="/">Go to the main page</Link>
    </>
  )
}

1
http://localhost:3000/helloworld12345678

# Streaming async components

In the following example, the async/page.tsx file is an async component that renders the page after 1 second, and the Abc and Xyz components are also async components that render their content after 2 and 3 seconds, respectively.
Then when you visit http://localhost:3000/async, the loading animation is shown for 4 seconds, and after that, the Abc and Xyz components render at the same time.
The Abc component could render after 2 seconds, but because of the Xyz component, it renders together with it after 3 seconds.

1
2
3
4
5
6
├─app/
│  ├─async/
│  │  ├─Abc.tsx
│  │  ├─loading.tsx
│  │  ├─page.tsx
│  │  └─Xyz.tsx

1
2
3
4
5
import Loader from '@/components/Loader'

export default function Loading() {
  return <Loader />
}

1
2
3
4
5
6
import wait from '@/utils/wait'

export default async function Abc() {
  await wait(2000)
  return <h2>Abc component!</h2>
}

1
2
3
4
5
6
import wait from '@/utils/wait'

export default async function Xyz() {
  await wait(3000)
  return <h2>Xyz component!</h2>
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import wait from '@/utils/wait'
import Abc from './Abc'
import Xyz from './Xyz'

export default async function Page() {
  await wait(1000)
  return (
    <>
      <h1>Async page!</h1>
      <Abc />
      <Xyz />
    </>
  )
}

Let's add a link in the <Header> component to the test page for streaming async components.

1
2
3
4
5
6
7
8
9
10
11
// Omitted..
const links = [
  { href: '/', label: 'Home' },
  { href: '/movies', label: 'Movies' },
  { href: '/movies/tt4154796', label: 'Movie(Avengers)' },
  { href: '/async', label: 'Async' }
]

export default function Header() {
  // Omitted..
}

If you stream async components with the <Suspense> component, each async component can render as soon as it's ready.
You can also render a loading UI for each async component with the fallback prop of the <Suspense> component.
In the following example, the default loading animation is shown for 1 second, then the red and blue loading animations are shown for 2 and 3 seconds, respectively, and then the Abc and Xyz components render.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import { Suspense } from 'react'
import Loader from '@/components/Loader'
import wait from '@/utils/wait'
import Abc from './Abc'
import Xyz from './Xyz'

export default async function Page() {
  await wait(1000)
  return (
    <>
      <h1>Async page!</h1>
      <Suspense fallback={<Loader color="red" />}>
        <Abc />
      </Suspense>
      <Suspense fallback={<Loader color="blue" />}>
        <Xyz />
      </Suspense>
    </>
  )
}

# Advanced routing patterns

# Route groups

Regular folders inside the /app folder always map to URL paths, but you can use parentheses (()) to create folder (route) groups that don't affect the URL path.
In particular, each of these groups can have its own layout (layout.tsx), so you can provide different layouts for different routes.

1
2
3
4
5
6
7
8
9
10
├─app/
│  ├─(movies)/
│  │  ├─movies/
│  │  │  ├─[movieId]/
│  │  │  │  ├─error.tsx
│  │  │  │  ├─loading.tsx
│  │  │  │  └─page.tsx
│  │  └─layout.tsx  <== Layout that works only in the (movies) group
│  ├─layout.tsx  <== Root layout
│  └─page.tsx

1
2
3
4
5
6
7
8
export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <div className="border-2 px-3 py-2">
      <p className="text-gray-500">Layout of the (movies) route group</p>
      {children}
    </div>
  )
}

# Parallel routes

Folders with the @ prefix are pages that don't affect the URL path, and they let a single layout render several routes in parallel (parallel routes).
This lets you load and render several pages or components in parallel, which shortens the total loading time compared to sequential loading and lets you show each component's loading state independently, for a better user experience.

Parallel routes

1
2
3
4
5
6
7
8
9
10
11
12
13
├─app
│  ├─async
│  │  ├─@abc
│  │  │  ├─default.tsx
│  │  │  ├─loading.tsx
│  │  │  └─page.tsx
│  │  ├─@xyz
│  │  │  ├─default.tsx
│  │  │  ├─loading.tsx
│  │  │  └─page.tsx
│  │  ├─layout.tsx
│  │  ├─loading.tsx
│  │  └─page.tsx

The default component is what renders instead when a slot doesn't match the current URL.
During navigation with the <Link> component, Next.js remembers which child page each slot was showing.
But on a full page load, such as a refresh or entering the address directly, that state can't be restored.
In that case, the slots that match the URL render their own page.tsx, but the remaining slots that don't match have nothing to render.
For example, if only the @abc slot has an /async/detail child route, refreshing at that address leaves the @xyz slot unable to find a page to render.
That's why you put a fallback page in each slot for cases like this.

Starting with v16, named (@) slots in segments that have child routes need an explicit default component, and the build fails without one.
If you have nothing to show, you can call notFound() or return null.
However, slots in segments without child routes, like /async in the example above, and slots under a catch-all route ([...name]) are exceptions, so the build passes even without a default component.
Once you add a child route later, the component becomes required, so we recommend writing it ahead of time.

1
2
3
4
5
6
7
import { notFound } from 'next/navigation'

export default function Default() {
  notFound()
  // Or
  return null
}

Write the content of each component in the order of the project structure, as follows.

1
2
3
4
5
import Loader from '@/components/Loader'

export default function Loading() {
  return <Loader color="red" />
}

1
2
3
4
5
6
import wait from '@/utils/wait'

export default async function Abc() {
  await wait(2000)
  return <h2>Abc component!</h2>
}

1
2
3
4
5
import Loader from '@/components/Loader'

export default function Loading() {
  return <Loader color="blue" />
}

1
2
3
4
5
6
import wait from '@/utils/wait'

export default async function Xyz() {
  await wait(3000)
  return <h2>Xyz component!</h2>
}

The page.tsx component at the same level as the layout.tsx component is passed as the children prop of layout.tsx, the @abc/page.tsx component as the abc prop, and the @xyz/page.tsx component as the xyz prop.
Then each passed component is rendered with JSX interpolation, like {children}.
If you use the LayoutProps type, the types of the slot props, along with children, are inferred from the folder structure.

1
2
3
4
5
6
7
8
9
10
11
12
13
export default function Layout({
  children,
  abc,
  xyz
}: LayoutProps<'/async'>) {
  return (
    <>
      {children}
      {abc}
      {xyz}
    </>
  )
}

1
2
3
4
5
import Loader from '@/components/Loader'

export default function Loading() {
  return <Loader />
}

1
2
3
4
5
6
import wait from '@/utils/wait'

export default async function Page() {
  await wait(1000)
  return <h1>Async page!</h1>
}

When you visit http://localhost:3000/async, you get the same loading animations and page results as in the <Suspense> example we saw in 'Streaming async components'.
The result is the same, but with parallel routes like this, each page component loads independently, and you can easily separate loading and error states for each component, which can reduce complex branching in your components.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import { Suspense } from 'react'
import Loader from '@/components/Loader'
import wait from '@/utils/wait'
import Abc from './Abc'
import Xyz from './Xyz'

export default async function Page() {
  await wait(1000)
  return (
    <>
      <h1>Async page!</h1>
      <Suspense fallback={<Loader color="red" />}>
        <Abc />
      </Suspense>
      <Suspense fallback={<Loader color="blue" />}>
        <Xyz />
      </Suspense>
    </>
  )
}

# Intercepting routes

In Next.js, the intercepting routes feature lets you render a different URL path within the current layout.

Naming conventions for intercepting routes, such as (..), are similar to relative paths (../, ./), but they're based on segments, not folders.
For example, 'route groups' aren't mapped to URLs, so the folder path /app/a/b/(group)/(..)x matches the URL path /a/x.

Intercepting routes

1
2
3
4
5
6
7
8
9
├─app
│  ├─a
│  │  └─b
│  │     └─c
│  │        ├─(...)x
│  │        │  └─page.tsx
│  │        └─page.tsx
│  └─x
│    └─page.tsx

1
2
3
export default function XPage() {
  return <h1>Intercepted X Page!!</h1>
}

1
2
3
4
5
6
7
8
9
10
import Link from 'next/link'

export default function CPage() {
  return (
    <>
      <h1>C Page</h1>
      <Link href="/x">Intercept!</Link>
    </>
  )
}

1
2
3
export default function XPage() {
  return <h1>X Page..</h1>
}

1
http://localhost:3000/a/b/c

1
2
3
4
5
6
7
8
9
10
11
12
├─app
│  ├─a
│  │  └─b
│  │     └─c
│  │        ├─@xWrap
│  │        │  ├─(...)x
│  │        │  │  └─page.tsx
│  │        │  └─page.tsx
│  │        ├─layout.tsx
│  │        └─page.tsx
│  └─x
│    └─page.tsx

..@xWrap/page.tsx returns null so that it doesn't show anything on screen by itself, and it's used to render the page of the intercepted route (@xWrap/(...)x/page.tsx).

1
2
3
export default function xWrap() {
  return null
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
export default function CLayout({
  children,
  xWrap
}: {
  children: React.ReactNode
  xWrap: React.ReactNode
}) {
  return (
    <>
      {children}
      {xWrap}
    </>
  )
}

# Proxy

With a single /proxy.ts file created in the root path, you can provide code that runs on the server before a request goes to a specific route.
It's mainly used to separate pages that need authentication and permission checks, and it can also set response headers and cookies, redirect, rewrite, and more.

Starting with Next.js 16, middleware.ts has been renamed to proxy.ts.
proxy.ts makes the network boundary clear and runs in the Node.js runtime.

Proxy runs in the following process.

1. Next.js Node.js runtime initialization
2. Running the Proxy that matches the requested route (config.matcher)
3. Static/dynamic route matching
4. Layout and page rendering

1
2
3
4
5
6
7
8
9
10
11
12
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function proxy(request: NextRequest) {
  return NextResponse.next()
}

// Proxy is called only on routes that match the matcher property.
// If you omit the `config` export, Proxy is called on every route.
export const config = {
  matcher: ['/dashboard/:path*', '...'] // Match only specific routes
}

By default, Proxy is called on every route request.
If you want to exclude specific routes, you can exclude certain patterns with a regular expression (RegExp) in the source property.
The (?!) expression means a negative lookahead, which excludes a specific pattern.
In other words, Proxy is called on all routes except the specified ones, and the following routes are excluded from Proxy.

• api/*: API routes
• _next/static/*: Static files
• _next/image/*: Image optimization files
• favicon.ico: Favicon file

1
2
3
4
5
6
7
8
9
10
11
12
13
// ...
export const config = {
  matcher: [
    {
      source: '/((?!api|_next/static|_next/image|favicon.ico).*)',
      // Exclude prefetch requests from Proxy!
      missing: [
        { type: 'header', key: 'next-router-prefetch' },
        { type: 'header', key: 'purpose', value: 'prefetch' }
      ]
    }
  ]
}

# API

You can define API endpoints through the structure inside the /app/api folder and handle requests for various HTTP methods, such as 'GET' and 'POST'.
This folder structure uses route.ts files instead of the basic file conventions such as page.tsx.

1
2
3
4
5
6
7
├─app
│  ├─api
│  │  ├─movies
│  │  │  └─[movieId]
│  │  │     └─route.ts
│  │  └─users
│  │     └─route.ts

The value of a dynamic route is passed in the params property of the handler's second argument (context), and you write its type by specifying a route string for the RouteContext type, just like PageProps for pages.

1
2
3
4
5
6
7
8
9
10
11
12
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export async function GET(
  request: NextRequest,
  context: RouteContext<'/api/movies/[movieId]'>
) {
  const { movieId } = await context.params // Dynamic route
  const res = await fetch(`https://omdbapi.com/?apikey=7035c60c&i=${movieId}`)
  const data = await res.json()
  return NextResponse.json(data)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

interface ResponseValue {
  total: number
  users: User[]
}
interface User {
  id: string
  name: string
  age: number
  isValid: boolean
  // ...
}

export async function POST(request: NextRequest) {
  // const body = await request.json() // Request body
  const searchParams = request.nextUrl.searchParams // Query string
  const sort = (searchParams.get('sort') || 'name') as keyof User

  // API: https://www.heropy.dev/p/5PlGxB
  const res = await fetch('https://api.heropy.dev/v0/users')
  const { users } = (await res.json()) as ResponseValue
  users.sort((a, b) => {
    const av = a[sort] || 0
    const bv = b[sort] || 0
    return av > bv ? 1 : -1
  })
  return NextResponse.json(users)
}

1
2
http://localhost:3000/api/movies/tt4520988
http://localhost:3000/api/users?sort=age

# Server Actions

Next.js lets you write functions that run only on the server (Server Actions).
A Server Action doesn't stop at changing data; if needed, the server also re-renders the screen with the change applied and sends it along in the response.
It differs from a simple API call in that the data change and the screen update are bundled together, and it must be called through a form submission, an event handler, and so on.

Add the 'use server' directive at the top of a module and add your Server Actions, as follows.

1
2
3
4
5
6
7
'use server'
export async function wait(duration = 1000): Promise<{ message: string }> {
  console.log(`Run 'wait' function`)
  return new Promise(resolve =>
    setTimeout(() => resolve({ message: `Waited for ${duration}ms` }), duration)
  )
}

As follows, you can also import and use Server Actions in Client Components.
Here too, the Run 'wait' function message is printed only in the server console.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
'use client'
import { wait } from '@/serverActions'
import { useState, useEffect } from 'react'

export default function ClientPage() {
  const [message, setMessage] = useState('')
  const [loading, setLoading] = useState(true)
  useEffect(() => {
    wait(3000).then(({ message }) => {
      setMessage(message)
      setLoading(false)
    })
  }, [])
  return <h1>{loading ? 'Loading...' : message}</h1>
}

In particular, Server Actions can be called through the action attribute of a <form> element, which makes them useful for working with forms.
The following example only shows how to connect a form to a Server Action.
For actual sign-in handling, see the Authentication section.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import { signIn } from '@/serverActions'

export default function Page() {
  return (
    <>
      <form
        action={signIn}
        className="flex gap-4">
        <input
          name="email"
          type="email"
          placeholder="Email"
          className="rounded px-2 py-1 text-gray-900 focus:outline-none focus:ring-2 focus:ring-blue-500"
        />
        <input
          name="password"
          type="password"
          placeholder="Password"
          className="rounded px-2 py-1 text-gray-900 focus:outline-none focus:ring-2 focus:ring-blue-500"
        />
        <button
          type="submit"
          className="rounded bg-blue-500 px-4 py-2 text-white hover:bg-blue-400">
          Sign in
        </button>
      </form>
    </>
  )
}

1
2
3
4
5
6
7
8
9
10
11
12
'use server'
import { redirect } from 'next/navigation'

export async function signIn(formData: FormData) {
  const email = formData.get('email')
  const password = formData.get('password')
  console.log(email, password)
  // await sign-in handling..
  redirect('/') // On successful sign-in, go to the main page!
}

// ...

Calling it directly from a Server Component, as follows, is just a regular function call that runs on the server, and it doesn't work as a Server Action.
A Server Action exists only when it's called through React's action mechanisms, such as the action attribute of a <form> element or an event handler, as a request separate from page rendering.

1
2
3
4
5
6
import { wait } from '@/serverActions'

export default async function ServerPage() {
  const { message } = await wait(3000)
  return <h1>{message}</h1>
}

# Authentication

When you implement user authentication in Next.js, the first thing to decide is where to store the session token.
Server Components, Server Actions, and Proxy all need to be able to read it, so you store it in an httpOnly cookie.

This creates a structure where the browser doesn't talk to the authentication API directly, and the Next.js server makes the calls on its behalf in the middle.
A bonus is that you don't have to include values that must not be exposed, such as API keys, in the client bundle.

Auth.js(NextAuth.js)

Let's integrate an external authentication API directly, without a library.
The API we'll use is as follows; every request header needs an issued API key, but it's omitted in this post.