Let me explain how Server and Client Components work in Next.js and when to use them, with examples of how to compose them together in your application.

When to use Server and Client Components?
The client and server environments have different capabilities. Server and client components allow you to run logic in each environment depending on your use case.

Use client Components when you need:

• Lifecycle logic. E.g. useEffect.

• State and event handlers. E.g. onClick, onChange.

• Browser-only APIs. E.g. localStorage, window, navogator.geolocation
  , etc.

• Custom hooks.

Use Server Components when you need:

• Fetch data from databases or APIs close to the source.

• Use API keys, tokens, and other secrets without exposing them to the client.

• Reduce the amount of JavaScript sent to the browser.

• Improve the First Contentful Paint(FCP) and stream content progressively to the client

For example, the <Page/> component is a Server Component that fetches data about a post and passes it as props to the <LinkButton/>, which handles client-side interactivity.

import LikeButton from '@/app/ui/like-button'
import { getPost } from '@/lib/data'
 
export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const post = await getPost(id)
 
  return (
    <div>
      <main>
        <h1>{post.title}</h1>
        {/* ... */}
        <LikeButton likes={post.likes} />
      </main>
    </div>
  )
}

'use client'
 
import { useState } from 'react'
 
export default function LikeButton({ likes }: { likes: number }) {
  // ...
}

How do Server and Client Components work in Next.js?

On the server

On the server, Next.js uses React's APIs to orchestrate rendering. The rendering work is split into chunks by individual route segments (layouts and pages):

• Server Components are rendered into a special data format called the React Server Component Payload(RSC Payload).

• Client Components and the RSC payload are used to prerender HTML.

What is the React Server Component Payload (RSC)?

The RSC Payload is a compact binary representation of the rendered React Server Components tree. It's used by React on the client to update the browser's DOM. The RSC Payload contains:

• The rendered result of Server Components

• Placeholders for where Client Components should be rendered and references to their JavaScript files

• Any props passed from a Server Component to a Client Component

On the client(first load)

1. HTML is used to immediately show a fast, non-interactive preview of the route to the user.

2. RSC Payload is used to reconcile the Client and Server Component trees.

3. JavaScript is used to hydrate Client Components and make the application interactive.

What is hydration?

Hydration is React's process for attaching event handlers to the DOM, to make the static HTML interactive.

What is inside the RSC Payload?

The payload contains the necessary information for the client to reconstruction the React component tree and update the DOM without needing to download or execute the original server Component JavaScript. Key contents include:

• Rendered Output: The final UI structure (Virtual DOM) of your Server Components

• Client Component References: Pointers to the specific JavaScript files needed to hydrate those Client Components.

• Client Component References: Pointers to the specific JavaScript files needed to hydrate those Client Components.

• Serialized Props: Any data passed from a Server Component to a Client Component as props.

• Suspense Information: Metadata for streaming content in chunks as it becomes ready.

How Next.js Uses It

1. On the Server: React renders Server Components into the RSC Payload. For the initial page load, Next.js uses this payload to generate the static HTML for a fast first paint.

2. On the Client: For subsequent navigations (e.g., using next/link), only the RSC Payload is sent to the browser. React then use this payload to reconcile the DOM and hydrate Client Components, making the page interactive

How to View It

You can inspect the payload in your browser's developer tools:

1. Open the Network tab.

2. Filter for requests with the content type text/x-component.

3. Click on a request to see the raw serialized React tree data.

1. Static Metadata: To set a fixed title or description, export the Metadata object.

// app/page.tsx or app/layout.tsx
import { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'Home | My Site',
  description: "This is the site's homepage.",
  keywords: ['Next.js', 'React', 'metadata'],
  openGraph: {
    title: 'Home | My Site',
    description: "This is the site's homepage.",
    url: 'https://example.com',
    siteName: 'My Site',
    images: [
      {
        url: 'https://example.com',
        width: 1200,
        height: 630,
      },
    ],
    locale: 'ja_JP',
    type: 'website',
  },
  twitter: {
    card: 'summary_large_image',
    title: 'Home | My Site',
    description: "This is the site's homepage.",
    images: ['https://example.com'],
  },
}

export default function Page() {
  return <h1>Hello!</h1>
}

2. Dynamic Metadata: If you wish to modify metadata based on URL parameters (params) or data from external APIs—for example, on blog post pages—use the generateMetadata function.

// app/posts/[id]/page.tsx
import { Metadata } from 'next'

type Props = {
  params: Promise<{ id: string }>
}

// Data retrieval function (as Next.js automatically memoises this, calling it again on the page will not affect performance)
async function getPost(id: string) {
  const res = await fetch(`https://example.com{id}`)
  return res.json()
}

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const id = (await params).id
  const post = await getPost(id)

  return {
    title: `${post.title} | マイサイト`,
    description: post.summary,
    openGraph: {
      title: post.title,
      description: post.summary,
      images: [post.coverImage],
    },
  }
}

export default async function Page({ params }: Props) {
  const id = (await params).id
  const post = await getPost(id)
  
  return <article><h1>{post.title}</h1></article>
}

3.By defining a template in the root layout.tsx file using the title template feature (title.template), you can partially replace the title on subpages.

// app/layout.tsx (root layout)
export const metadata: Metadata = {
  title: {
    template: '%s | MySite',
    default: 'MySite - Official Home', // Default used when a child page has no title
  },
}

// app/about/page.tsx (Company overview page)
export const metadata: Metadata = {
  title: 'Company Overview', // In the browser this will appear as "Company Overview | MySite"
}

4. File based meta data

Instead of writing the code yourself, simply place the files in a specific folder within the app directory, and Next.js will automatically recognise and generate the meta tags for you.

• Icons: favicon.ico（root directory only）、icon.png、apple-icon.png

• Social media sharing images: opengraph-image.png、twitter-image.png

• For search engine crawlers: robots.txt、sitemap.xml

💡 Note (Important) Exporting metadata via code (metadata / generateMetadata) is supported only in server components. Since it cannot be exported from client component files that declare “use client,” please define it in the parent layout or page (on the server side) in such cases.

The latest versions of Next.js (Next.js 15, 16) have shifted from automatically caching everything to making caching developer-directed.

Main cache features (App Router)

Next.js has four independent caching layers between the server and the client.

Latest cache control: use cache [1]

In Next.js 15/16, the new use cache directive was introduced. This allows intuitive caching to be specified at the level of functions or components. [1, 2, 3]

1. Data-level caching: Cache specific data-fetching functions.

   export async function getProducts() {
     'use cache' // この関数をキャッシュする
     const data = await db.query('...')
     return data
   }
   

2. UI-level caching: Cache the rendered output of an entire component.

   async function HeavyComponent() {
     'use cache'
     return <div>重い処理の結果</div>
   

By stream, you can prevent slow data requests from blocking your whole page. This allows the user to see and interact with parts of the page without waiting for all the data to load before any UI can be shown to the user.

Streaming works well with React's component model, as each component can be considered a chunk.

There are two ways you implement streaming in Next.js:
1. At the page level, with the loading.ts file(which creates <Suspense> for you

2. At the component level, with <Suspense> for more granular control.

**Streaming a whole page with `loading.tsx` **

In the `/app/dashboard` folder, create a new file called `loading.tsx`:

export default function Loading() {
  return <div>Loading...</div>;
}

A few things are happening here:

1. loading.tsx is a special Next.js file built on top of React Suspense. It allows you to create fallback UI to show as a replacement while page content loads.

2. Since <SideNav> is static, it's shown immediately. The user can interact with <SideNav> while the dynamic content is loading.

3. The user doesn't have to wait for the page to finish loading before navigating away (this is called interruptable navigation).

Congratulations! You've just implemented streaming. But we can do more to improve the user experience. Let's show a loading skeleton instead of the Loading… text.

**Adding loading skeltons**

A loading skeleton is a simplified version of the UI. Many websites use them as a placeholder(or fallback) to indicate to users that the content is loading. Any UI you add in loading.tsx will be embedded as part of a static file, and sent first. Then, the rest of the dynamic content will be streamed from the server to the client.

Inside your loading.tsx file, import a new component called <DashboardSkeleton>:

import DashboardSkeleton from '@/app/ui/skeletons';
 
export default function Loading() {
  return <DashboardSkeleton />;
}

**Fixing the loading skeleton bug with route groups**
Right now, your loading skeleton will apply to the invoices.

Since loading.tsx is a level higher than /invoices/page.tsx and /customers/page.tsx in the file system, it's also applied to those pages.

We can change this with Route Groups. Create a new folder called /(overview) inside the dashboard folder. Then, move your loading.tsx and page.tsx files inside the folder:

Now, the loading.tsx file will only apply to your dashboard overview page.

Route groups allow you to organize files into logical groups without affecting the URL path structure. When you create a new folder using parentheses (), the name won't be included in the URL path. So /dashboard/(overview)/page.tsx becomes /dashboard.

Here, you're using a route group to ensure loading.tsx only applies to your dashboard overview page. However, you can also use route groups to separate your application into sections (e.g. (marketing) routes and (shop) routes) or by teams for larger applications.

**Streaming a component**

So far, you're streaming a whole page. But you can also be more granular and stream specific components using React Suspense.

Suspense allows you to defer reading parts of your application until some condition is met. You can wrap your dynamic components in Suspense. Then, pass it a fallback component to show while the dynamic component loads.

If you remember the slow data request, fetchRevenue(), this is the request that is slowing down the whole page. Instead of blocking your whole page, you can use Suspense to stream only this component and immediately show the rest of the page's UI.

To do so, you'll need to move the data fetch to the component, let's update the code to see what that'll look like:

Delete all instances of fetchRevenue() and its data from /dashboard/(overview)/page.tsx:

import { Card } from '@/app/ui/dashboard/cards';
import RevenueChart from '@/app/ui/dashboard/revenue-chart';
import LatestInvoices from '@/app/ui/dashboard/latest-invoices';
import { lusitana } from '@/app/ui/fonts';
import { fetchLatestInvoices, fetchCardData } from '@/app/lib/data'; // remove fetchRevenue
 
export default async function Page() {
  const revenue = await fetchRevenue() // delete this line
  const latestInvoices = await fetchLatestInvoices();
  const {
    numberOfInvoices,
    numberOfCustomers,
    totalPaidInvoices,
    totalPendingInvoices,
  } = await fetchCardData();
 
  return (
    // ...
  );
}

Then, import <Suspense> from React, and wrap it around <RevenueChart />. You can pass it a fallback component called <RevenueChartSkeleton>.

import { Card } from '@/app/ui/dashboard/cards';
import RevenueChart from '@/app/ui/dashboard/revenue-chart';
import LatestInvoices from '@/app/ui/dashboard/latest-invoices';
import { lusitana } from '@/app/ui/fonts';
import { fetchLatestInvoices, fetchCardData } from '@/app/lib/data';
import { Suspense } from 'react';
import { RevenueChartSkeleton } from '@/app/ui/skeletons';
 
export default async function Page() {
  const latestInvoices = await fetchLatestInvoices();
  const {
    numberOfInvoices,
    numberOfCustomers,
    totalPaidInvoices,
    totalPendingInvoices,
  } = await fetchCardData();
 
  return (
    <main>
      <h1 className={`${lusitana.className} mb-4 text-xl md:text-2xl`}>
        Dashboard
      </h1>
      <div className="grid gap-6 sm:grid-cols-2 lg:grid-cols-4">
        <Card title="Collected" value={totalPaidInvoices} type="collected" />
        <Card title="Pending" value={totalPendingInvoices} type="pending" />
        <Card title="Total Invoices" value={numberOfInvoices} type="invoices" />
        <Card
          title="Total Customers"
          value={numberOfCustomers}
          type="customers"
        />
      </div>
      <div className="mt-6 grid grid-cols-1 gap-6 md:grid-cols-4 lg:grid-cols-8">
        <Suspense fallback={<RevenueChartSkeleton />}>
          <RevenueChart />
        </Suspense>
        <LatestInvoices latestInvoices={latestInvoices} />
      </div>
    </main>
  );
}

Finally, update the <RevenueChart> component to fetch its own data and remove the prop passed to it:

import { generateYAxis } from '@/app/lib/utils';
import { CalendarIcon } from '@heroicons/react/24/outline';
import { lusitana } from '@/app/ui/fonts';
import { fetchRevenue } from '@/app/lib/data';
 
// ...
 
export default async function RevenueChart() { // Make component async, remove the props
  const revenue = await fetchRevenue(); // Fetch data inside the component
 
  const chartHeight = 350;
  const { yAxisLabels, topLabel } = generateYAxis(revenue);
 
  if (!revenue || revenue.length === 0) {
    return <p className="mt-4 text-gray-400">No data available.</p>;
  }
 
  return (
    // ...
  );
}
 

Now refresh the page, you should see the dashboard information almost immediately, while a fallback skeleton is shown for <RevenueChart>:

**Practice: Streaming** <LatestInvoices>

Now it's your turn! Practice what you've just learned by streaming the <LatestInvoices> component.

Move fetchLatestInvoices() down from the page to the <LatestInvoices> component. Wrap the component in a <Suspense> boundary with a fallback called <LatestInvoicesSkeleton>.

Once you're ready, expand the toggle to see the solution code:

import { Card } from '@/app/ui/dashboard/cards';
import RevenueChart from '@/app/ui/dashboard/revenue-chart';
import LatestInvoices from '@/app/ui/dashboard/latest-invoices';
import { lusitana } from '@/app/ui/fonts';
import { fetchCardData } from '@/app/lib/data'; // Remove fetchLatestInvoices
import { Suspense } from 'react';
import {
  RevenueChartSkeleton,
  LatestInvoicesSkeleton,
} from '@/app/ui/skeletons';
 
export default async function Page() {
  // Remove `const latestInvoices = await fetchLatestInvoices()`
  const {
    numberOfInvoices,
    numberOfCustomers,
    totalPaidInvoices,
    totalPendingInvoices,
  } = await fetchCardData();
 
  return (
    <main>
      <h1 className={`${lusitana.className} mb-4 text-xl md:text-2xl`}>
        Dashboard
      </h1>
      <div className="grid gap-6 sm:grid-cols-2 lg:grid-cols-4">
        <Card title="Collected" value={totalPaidInvoices} type="collected" />
        <Card title="Pending" value={totalPendingInvoices} type="pending" />
        <Card title="Total Invoices" value={numberOfInvoices} type="invoices" />
        <Card
          title="Total Customers"
          value={numberOfCustomers}
          type="customers"
        />
      </div>
      <div className="mt-6 grid grid-cols-1 gap-6 md:grid-cols-4 lg:grid-cols-8">
        <Suspense fallback={<RevenueChartSkeleton />}>
          <RevenueChart />
        </Suspense>
        <Suspense fallback={<LatestInvoicesSkeleton />}>
          <LatestInvoices />
        </Suspense>
      </div>
    </main>
  );
}

**Grouping components**
To create more of a staggered effect, you can group the cards using a wrapper component. This means the static <SideNav/> will be shown first, followed by the cards, etc.

In your page.tsx file:

1. Delete your <Card> components.

2. Delete the fetchCardData() function.

3. Import a new wrapper component called <CardWrapper />.

4. Import a new skeleton component called <CardsSkeleton />.

5. Wrap <CardWrapper /> in Suspense.

import CardWrapper from '@/app/ui/dashboard/cards';
// ...
import {
  RevenueChartSkeleton,
  LatestInvoicesSkeleton,
  CardsSkeleton,
} from '@/app/ui/skeletons';
 
export default async function Page() {
  return (
    <main>
      <h1 className={`${lusitana.className} mb-4 text-xl md:text-2xl`}>
        Dashboard
      </h1>
      <div className="grid gap-6 sm:grid-cols-2 lg:grid-cols-4">
        <Suspense fallback={<CardsSkeleton />}>
          <CardWrapper />
        </Suspense>
      </div>
      // ...
    </main>
  );
}

Then, move into the file /app/ui/dashboard/cards.tsx, import the fetchCardData() function, and invoke it inside the <CardWrapper/> component. Make sure to uncomment any necessary code in this component.

// ...
import { fetchCardData } from '@/app/lib/data';
 
// ...
 
export default async function CardWrapper() {
  const {
    numberOfInvoices,
    numberOfCustomers,
    totalPaidInvoices,
    totalPendingInvoices,
  } = await fetchCardData();
 
  return (
    <>
      <Card title="Collected" value={totalPaidInvoices} type="collected" />
      <Card title="Pending" value={totalPendingInvoices} type="pending" />
      <Card title="Total Invoices" value={numberOfInvoices} type="invoices" />
      <Card
        title="Total Customers"
        value={numberOfCustomers}
        type="customers"
      />
    </>
  );
}

Refresh the page, and you should see all the cards load in at the same time. You can use this pattern when you want multiple components to load in at the same time.

Deciding where to place your Suspense boundaries

Where you place your Suspense boundaries will depend on a few things:

1. How you want the user to experience the page as it streams.

2. What content you want to prioritize.

3. If the components rely on data fetching.

Take a look at your dashboard page, is there anything you would've done differently?

Don't worry. There isn't a right answer.

• You could stream the whole page like we did with loading.tsx... but that may lead to a longer loading time if one of the components has a slow data fetch.

• You could stream every component individually... but that may lead to UI popping into the screen as it becomes ready.

• You could also create a staggered effect by streaming page sections. But you'll need to create wrapper components.

Where you place your suspense boundaries will vary depending on your application. In general, it's good practice to move your data fetches down to the components that need it, and then wrap those components in Suspense. But there is nothing wrong with streaming the sections or the whole page if that's what your application needs.

Don't be afraid to experiment with Suspense and see what works best, it's a powerful API that can help you create more delightful user experiences.

Next.js 15 introduced use cache directive.

・This is a new mechanism that allows you to declare “cache this output” on a per-function or per-component basis.

・You can intuitively specify the scope of caching without using complex APIs such as the traditional unstable_cache.

・Next.js 16 introduced PPR(Partial Pre Rendering), which enhances the mechanism for delivering content quickly by combining cached static content with dynamic content.

Cache Refresh (Revalidation) There are two main ways to refresh cached data.

Time-based Revalidation: Specify the number of seconds using the next: { revalidate: 60 } option in the fetch request.

On-demand Revalidation: Use revalidatePath or revalidateTag to explicitly invalidate the cache when a data mutation occurs.

**Main features are follows:**

・Many authentications: OAuth provider such as Google, Github, Twitter, also support main(majic link) and ID/pasword authentication.

・Next.js Optimization: Designed to integrate seamlessly with Next.js API routes and server components, enabling efficient security and session management.

・Flexible Data Management: By using database adapters, you can manage user information and sessions in your own database (MySQL, PostgreSQL, MongoDB, etc.).

・Latest Auth.js (v5): Starting with the latest v5 series, it has evolved into a comprehensive authentication library called “Auth.js” that supports not only Next.js but also other frameworks such as SvelteKit and SolidStart.

**Benefits of Implementation **
Building an authentication system from scratch requires a tremendous amount of time to implement security measures and adapt to specification changes from various providers. With NextAuth.js, you can implement a secure authentication flow with just a few lines of configuration, significantly improving development efficiency.

I introduce you follows:
・ What is Edge Runtime?
・ What is the difference for Node.js Runtime?
・ Can you use Node.js on Runtime?

**The role of middleware**
Middleware, as the name suggests, is a mechanism that processes requests between the client and server. Examples of the purposes for which middleware can be used include:

• redirecting to the login screen when accessing the login URL before authentication;

• capturing the request data and logging it;

• changing the path for each request for A/B testing purposes and returning it.

For more specific examples, please refer to the Next.js official documentation.

**What is Edge Runtime ?**
Next.js middleware runs on Edge Runtime. Edge runtime is the environment in which JavaScript runs with limited functionalities.

Edge Runtime adapts the V8 engine and supports Web APIs such as fetch, Request, and Response .

While it doesn't support Node.js native APIs such as ` fs `, ` http `, and `crypto.`

Therefore, if you need to encrypt authentication credentials within the middleware or access the file system, you cannot use Node.js APIs and must instead consider alternative approaches, such as using external modules or moving the functionality to the application layer. For details on supported APIs, please refer to the Edge Runtime chapter in the official documentation.

Edge Runtime is designed for using edge computing and has been optimized for lightweight performance by carefully selecting only the necessary features.

Edge computing includes:

• Vercel Edge Functions

• AWS LambdaEDGE

• Cloudflare Workers

Most of them are limited by the size of memory or code for optimization performance. For example, Vercel is designed for a limitation of 1MB〜4MB code size or a response within 25s, which causes the timeout error.

**In Next.js v15, we can use Node.js in middleware on runtime enviroment.**
We can use Node.js in middleware on runtime envoriment experimentally.
This allows us to use fs , http .

**Points to Consider*
We can use Node.js's native APIs to add more complex features to the middleware. However, we must consider the impact on performance and resource consumption.

**Keep middleware as simple as possible*
Middleware essentially works on requests or responses. We have to restrict jobs to simple tasks such as header manipulation and redirects, and move heavy work to the server. If we need to use the Node.js native API, use it.

1. Request Forwarding and Rewriting (Rewrites) This is used to bypass cross-origin restrictions (CORS) in development environments or to proxy specific paths (e.g., /api/:path*) to an external backend server. Configure this in next.config.js.

// next.config.ts
module.exports = {
  async rewrites() {
    return [
      {
        source: '/api/:path*',
        destination: 'https://backend-api.com*',
      },
    ];
  },
};

1. Proxy (formerly Middleware) in Next.js 16 and later Starting with Next.js 16, you can create a proxy.ts (or proxy.js) file in the project root to perform tasks such as authentication checks, logging, and header modifications before the request is completed.

File name: proxy.ts or proxy.js Role: Executed before rendering; allows for redirects and response rewriting Note: The traditional middleware.ts is deprecated, and migration to proxy.ts is recommended.

//proxy.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function proxy(request: NextRequest) {
  // 認証チェックなどのロジック
  if (request.nextUrl.pathname.startsWith('/dashboard')) {
    // リダイレクトや書き換えの処理
    return NextResponse.rewrite(new URL('/login', request.url))
  }
}

GET /api/users
POST /api/users
GET /api/users/[id]
PUT /api/users/[id]
DELETE /api/users/[id]

You define the method in the file.

//app/api/users/route.ts
import { NextRequest, NextResponse } from "next/server";

export function GET(request: NextRequest): NextResponse {
    // GET /api/users request
}

export function POST(request: NextRequest): NextResponse {
    // POST /api/users request
}

//app/api/users/[id]/route.ts

import { NextRequest, NextResponse } from "next/server";

export function GET(request: NextRequest, { params }: { params: { id: string } }): NextResponse {
    // GET /api/users/[id] request
}

export function PUT(request: NextRequest, { params }: { params: { id: string } }): NextResponse {
    // PUT /api/users/[id] request
}

export function DELETE(request: NextRequest, { params }: { params: { id: string } }): NextResponse {
    // DELETE /api/users/[id] request
}

As a result, you can deal with each handling.

**Query Parameter**

// ...
//e.g）GET /api/users?query=hoge 
export function GET(request: NextRequest): NextResponse {
  const params = request.nextUrl.searchParams;
  const query = params.get("query");
  // query = "hoge"
// ...

**Request Body**

// ...
// e.g）POST /api/users (request body: {"key": "hoge"}) 
export async function POST(request: NextRequest): Promise<NextResponse> {
  const params = await request.json();
  // params = {key: "hoge"}
// ...

Pass Parameter

// ...
// 例）POST /api/users (request body: {"key": "hoge"}) 
export async function POST(request: NextRequest): Promise<NextResponse> {
  const params = await request.json();
  // params = {key: "hoge"}
// ...

If multiple parameters are included, add those of types to param.

// ...
// e.g) GET /api/users/hoge/items/1
export function GET(request: NextRequest, { params }: { params: { id: string, itemId: number } }): NextResponse {
    // params.id = "hoge"
    // params.itemId = 1
}
// ...

**CORS**
If you access the API from different domain, you can defind the CORS to share the souce.

export function GET(request: NextRequest): NextResponse {
    return NextResponse.json(
        { response: "Test response." },
        {
          status: 200,  // Status code
          headers: {    // Response header
            "Access-Control-Allow-Origin": "*",
            "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
            "Access-Control-Allow-Headers": "Content-Type, Authorization",
          },
        },
  );
}

When defining the header in the response object, you can also define the CORS header. If there are too many endpoints, it is better to define the header in the middleware, because the header may become redundant.

Next.js provides “API Routes” as a mechanism that allows you to implement backend-like processing beyond the scope of the frontend. Simply put, this is a feature that lets you define server-side processing (API endpoints) within Next.js.

For example, it is used in the following scenarios:

・Querying a database to retrieve and return data

・Receiving form submissions and sending emails or saving the data

・Acting as a server-side intermediary for communication with external APIs

・Processing and validating authentication tokens and cookies on the server

This is particularly beneficial for developers who:

・Are working as individuals or in small teams and prioritize speed

・Want to work efficiently without separating UI development from API implementation

・Want to handle the minimum implementation themselves, even with limited backend experience

Additionally, within the Next.js App Router configuration, you can define API routes in the same way by using the app/api/ directory

That said, many of you may have questions like the following:

・Is it safe to use API Routes in production?

・What types of tasks are they best suited for?

・How do they differ from fetch and axios?

What’s the difference between the Pages Router and the App Router?

In this article, we’ll address these questions while introducing common patterns and best practices used in real-world scenarios.

2. Basic Syntax and Directory Structure of API Routes

Next.js API Routes provide a mechanism for defining server-side logic using simple syntax. They support both App Router and Pages Router configurations, and the syntax and placement differ slightly between the two.

✅Basic Syntax for Pages Router Configuration

In Pages Router, files placed under the pages/api/ folder are automatically recognized as endpoints.

// pages/api/hello.ts
import type { NextApiRequest, NextApiResponse } from 'next';

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ message: 'Hello API!' });
}

In this case, accessing /api/hello will return { message: “Hello API!” }.

You can use req.method to handle POST, GET, PUT, and other requests.

You can also handle database connections and session management within this code.

✅Basic Syntax for App Router Configuration (Next.js 13 and later)

In App Router, you must create files within the app/api/ directory and export HTTP method functions (such as GET and POST) on a per-file basis.

// app/api/hello/route.ts
import { NextResponse } from 'next/server';

export async function GET() {
  return NextResponse.json({ message: 'Hello from App Router!'         });
}

In the App Router configuration, the key point is that the file name is route.ts. This allows Next.js to recognize this file as an API endpoint.

The supported methods are as follows:

GET()

POST(req: Request)

PUT()

DELETE()

PATCH()

If necessary, use the Request object to retrieve the request body as follows:

export async function POST(req: Request) {
  const body = await req.json();
  return NextResponse.json({ received: body });
}

📁 Example of folder structure (App Router)

app/
  api/
    hello/
      route.ts         ← /api/hello
    contact/
      route.ts         ← /api/contact

🧩 Using with Middleware

API Routes can be combined with Next.js middleware (middleware.ts) and functions like headers() to enable advanced control features such as token authentication and redirect management.

① Form Submission Processing (e.g., Contact Form)

For example, when creating a “contact form,” the basic process involves sending and processing the information entered by the user via an API route.

✅ Benefits

Validation and submission processing can be separated from the front end

Flexible implementation of anti-spam measures and authentication logic

🔒 ② Secure authentication and authorization (JWT and session management)

For authentication, we may integrate with external services such as Firebase Authentication or Auth0, while performing token verification and user data protection within the API routes.

// app/api/user/route.ts
import { verifyToken } from '@/lib/auth';

export async function GET(req: Request) {
  const token = req.headers.get('Authorization')?.replace('Bearer ', '');
  const user = await verifyToken(token);
  if (!user) return new Response('Unauthorized', { status: 401 });
  return new Response(JSON.stringify({ user }), { status: 200 });
}

📂 ③ Integration with external APIs (indirect proxy)

API Routes are often used as a proxy to integrate with external APIs (such as OpenAI, Stripe, and Google APIs).

// app/api/openai/route.ts
export async function POST(req: Request) {
  const { prompt } = await req.json();
  const response = await fetch('https://api.openai.com/v1/chat/completions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ model: 'gpt-4', messages: [{ role: 'user', content: prompt }] }),
  });

  const data = await response.json();
  return new Response(JSON.stringify({ result: data }), { status: 200 });
}

✅ Benefits

You can safely call the API without exposing the API key to the front end

Front-end code becomes simpler

💾 ④ Integration with Databases (Prisma / Supabase / Firestore)

It is common to perform database operations within Next.js API routes using ORMs (e.g., Prisma) or client SDKs (e.g., Supabase, Firebase).

// app/api/todos/route.ts
import { prisma } from '@/lib/prisma';

export async function GET() {
  const todos = await prisma.todo.findMany();
  return Response.json(todos);
}

✅ Benefits

Optimizes data retrieval processes in an SSR environment

Eliminates the need for client-side database knowledge

4. Precautions and Best Practices for Using API Routes

While API Routes are convenient and flexible, improper design or operation can lead to spaghetti code and create security risks. In this chapter, we will introduce key points to keep in mind and best practices for using API Routes in real-world scenarios.

🧱 Improve Readability with a Thoughtful Directory Structure

As the number of API routes increases, your files can become cluttered. By creating a subdirectory for each endpoint, you can achieve a scalable structure.

/app
 └── api
     ├── contact
     │    └── route.ts
     ├── auth
     │    └── login/route.ts
     │    └── logout/route.ts
     └── todos
          ├── route.ts
          └── [id]/route.ts

✅ Key point: Grouping by functional units or resources helps minimize confusion even in team-based development

🔐 Standardize authentication and authorization mechanisms as much as possible

If many API routes require user authentication, it’s helpful to centralize authorization checks in middleware.ts or handle them in lib/auth.ts.

// lib/auth.ts
export async function getUserFromRequest(req: Request) {
  const token = extractToken(req);
  return await verifyToken(token);
}

✅ Key point: Hard-coding authentication logic for each API can easily lead to bugs.

🚧 Handle errors carefully

To ensure that the client displays the correct information when an API call fails, proper error handling and clear HTTP status codes are essential.

try {
  const data = await fetchSomething();
  return Response.json(data);
} catch (error) {
  console.error(error);
  return new Response('Internal Server Error', { status: 500 });
}

✅ Key point: Receiving a specific error message rather than a “500 error” on the client side improves the user experience

🚨 Division of Responsibilities with Client Components

Using fetch(‘/api/~’) directly in a Client Component tends to complicate state management and error handling.

Retrieve lightweight data using useSWR or React Query

Separate responsibilities for heavy processing into Server Components or API Routes

✅ Key Point: Clearly define where data is stored and where it is processed

📉 Don’t forget security measures like rate limiting and CSRF protection

The following measures are especially important for publicly exposed APIs (e.g., forms):

Rate Limit: Protection against bots and DDoS attacks

CSRF Token: Prevention of unintended requests

CORS Control: Allow requests only from authorized domains

✅ Key Point: Since Next.js alone cannot fully secure all areas, consider implementing a WAF or Cloudflare

✅ Conclusion | The key to API Routes is “simple design” Next.js API Routes are a very powerful feature for developing small to medium-sized applications. They are particularly well-suited for Server Components in App Router configurations and are ideal when you just need a “quick API.”

However, as the scale expands, considerations such as separation of concerns, security measures, and performance optimization become necessary.

In your own development, make sure to understand the “appropriate use cases” and “precautions” so you can use API Routes effectively.

With Parallel Routes, you can render multiple pages simultaneously or conditionally within the same layout. Taking the dashboard as an example, you can render the team page and the analytics page in parallel as shown below

Features and Main Uses

Routing Exclusion: Even if placed under the app directory, the page.js file within it will not be recognized as a URL.

File Organization: You can organize and manage page-specific components, CSS, and utility functions by keeping them in a physically close location (within a folder).

Naming Conventions: Start with an underscore, such as _folderName.

Examples of Use

app/
├── (auth)/
├── dashboard/
│   ├── _components/  <-- Private folder (not influence URL)
│   │   └── Chart.tsx
│   └── page.tsx      <-- access dashboard page by /dashboard
└── page.tsx

For example, pages/shop/[...slug].js will match /shop/clothes, but also /shop/clothes/tops, /shop/clothes/tops/t-shirts, and so on.

For example:

pages/shop/[...slug].js /shop/a { slug: ['a'] }

pages/shop/[...slug].js /shop/a/b { slug: ['a', 'b'] }

pages/shop/[...slug].js /shop/a/b/c { slug: ['a', 'b', 'c'] }

Catch-all segments ([...slug]) are extremely useful when URL hierarchies are deep and their exact depth is unknown. They are primarily used in the following three scenarios:

1. Hierarchical structures for documentation or blogs These are ideal for handling deep hierarchies—such as “category / subcategory / article title”—in a single template, as seen on documentation sites. Example: app/docs/[...slug]/page.tsx

2. E-commerce Site Filtering Used for structures where product categories, brands, sizes, etc., are concatenated as URL segments. Example: /shop/clothes/tops/t-shirts Advantage: Since each segment (clothes, tops...) can be retrieved as an array, it’s easy to reuse them directly as database query conditions.

3. Building CMSs and File Browsers This is well-suited for systems where users can freely create folders (hierarchies), such as tools like Notion or file management systems like Google Drive.

Key Features and Use Cases

・Organization and Grouping: Organize directories by function, such as pre-login (auth) and post-login (dashboard).

・Selective Layout Application: Apply a common layout (layout.tsx) only within specific groups.

・No Impact on URLs: Grouped folder names are not reflected in the URL.

・Multiple Root Layouts: You can separate root layouts (including the <html> tag) for each root group within different app directories.

Implementation Example

By organizing the folder structure as shown below, you can flexibly manage the layout—for example, by using different layouts for the /about page depending on whether the user is authenticated.

app/
├── (auth)/
│   ├── login/
│   │   └── page.tsx
│   └── layout.tsx  // Login Layout
└── (dashboard)/
    ├── dashboard/
    │   └── page.tsx
    └── layout.tsx  // Dashboard Layout

Dynamic Routes are defined using square brackets []. For example, if you create a file named app/products/[id]/page.tsx, it will generate pages that match URLs such as /products/1 and /products/2.

app/
└── products/
　　　└── [id]/
　　　　　　└── page.tsx

export default function ProductPage({ params }: { params: { category: string, id: string } }) {
  return (
    <>
      <h1>Category: {params.category}</h1>
      <h2>Product ID: {params.id}</h2>
    </>
  )
}

Key Features and Benefits of App Router

・Advanced routing: The folder structure under the app/ directory corresponds to URL paths. Define screens in page.tsx and common layouts in layout.tsx.

・Nested layouts: Layouts can be nested by folder, enabling efficient reuse of common UI elements.

・Improved data fetching: Data can be fetched directly within components using async/await. The fetch API has been extended to support powerful caching and revalidation.

・Simplified UI management: Simply placing loading.tsx (loading UI) and error.tsx (error handling) applies Suspense and Error Boundaries.

Server Components vs Client Components

・Server Components (.tsx): Default. Runs on the backend. Can access databases and APIs directly.

・Client Components (“use client”;): Used when interactivity (useState, useEffect, event listeners) is required