2nd/10_Wiki/Topics/Frontend/Nextjs_Framework.md

---
id: wiki-2026-0508-nextjs-framework
title: Next.js Framework
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Next.js, NextJS, Nextjs]
duplicate_of: none
source_trust_level: A
confidence_score: 0.95
verification_status: applied
tags: [nextjs, react, ssr, framework, vercel]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: TypeScript
  framework: Next.js 15
---

# Next.js Framework

## 매 한 줄
> **"매 Next.js 는 React-based full-stack framework — App Router (RSC) + Server Actions + Turbopack 의 조합"**. 2026 의 Next 15 는 매 React 19 RSC + Partial Prerendering (PPR) 안정화 + Turbopack 가 default. 매 Vercel 의 commercial backing.

## 매 핵심

### 매 Render 모드 (App Router)
- **Static (default)**: 매 build-time, ISR 가능.
- **Dynamic**: 매 request-time, `cookies()` / `headers()` 사용 시 자동 전환.
- **Streaming SSR**: 매 RSC + Suspense — 매 progressive HTML.
- **PPR (Partial Prerendering)**: 매 static shell + dynamic holes — 매 Next 15 default.

### 매 핵심 API
- **Server Components**: 매 default — 매 zero JS 전송.
- **`"use client"`**: 매 client component boundary.
- **Server Actions** (`"use server"`): 매 form / mutation, RPC 자동.
- **`fetch()` extension**: 매 cache, revalidate, tags.

### 매 응용
1. E-commerce (Shopify Hydrogen 영향).
2. Marketing site + blog (ISR 강점).
3. SaaS dashboard (RSC 로 bundle 감소).
4. AI chat UI — 매 streaming Server Action.

## 💻 패턴

### Server Component data fetch
```tsx
// app/posts/page.tsx — 매 server component, async 가능
async function PostsPage() {
  const posts = await fetch("https://api.example.com/posts", {
    next: { revalidate: 60, tags: ["posts"] },
  }).then((r) => r.json());

  return (
    <ul>
      {posts.map((p) => <li key={p.id}>{p.title}</li>)}
    </ul>
  );
}
export default PostsPage;
```

### Server Action (form mutation)
```tsx
// app/actions.ts
"use server";
import { revalidateTag } from "next/cache";

export async function createPost(formData: FormData) {
  await db.post.create({ data: { title: formData.get("title") as string } });
  revalidateTag("posts");
}

// app/new/page.tsx
import { createPost } from "../actions";
export default function NewPost() {
  return (
    <form action={createPost}>
      <input name="title" />
      <button type="submit">Save</button>
    </form>
  );
}
```

### Streaming with Suspense
```tsx
import { Suspense } from "react";

export default function Page() {
  return (
    <>
      <Header />  {/* 매 즉시 stream */}
      <Suspense fallback={<Skeleton />}>
        <SlowProductList /> {/* 매 fetch 끝나면 stream-in */}
      </Suspense>
    </>
  );
}
```

### Partial Prerendering (Next 15)
```tsx
// next.config.js
module.exports = {
  experimental: { ppr: "incremental" },
};

// app/page.tsx — static shell + dynamic part
export const experimental_ppr = true;

import { cookies } from "next/headers";
async function CartCount() {
  const session = (await cookies()).get("session");
  // 매 dynamic — static shell 의 hole 로 stream
  return <span>{await getCartCount(session?.value)}</span>;
}

export default function Page() {
  return (
    <>
      <StaticHeader />
      <Suspense fallback="0"><CartCount /></Suspense>
    </>
  );
}
```

### Route Handler (REST endpoint)
```ts
// app/api/users/route.ts
import { NextResponse } from "next/server";
export async function GET() {
  const users = await db.user.findMany();
  return NextResponse.json(users);
}
export async function POST(req: Request) {
  const body = await req.json();
  const user = await db.user.create({ data: body });
  return NextResponse.json(user, { status: 201 });
}
```

### Middleware (auth gate)
```ts
// middleware.ts
import { NextResponse, type NextRequest } from "next/server";
export function middleware(req: NextRequest) {
  const token = req.cookies.get("token");
  if (!token && req.nextUrl.pathname.startsWith("/dashboard")) {
    return NextResponse.redirect(new URL("/login", req.url));
  }
}
export const config = { matcher: ["/dashboard/:path*"] };
```

### Image optimization
```tsx
import Image from "next/image";
<Image src="/hero.jpg" width={1200} height={600} alt="" priority />
// 매 자동 AVIF/WebP, srcset, lazy
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| Marketing site | Static + ISR |
| User dashboard | RSC + Server Action |
| Realtime chat | "use client" + WebSocket |
| Mostly static + cart | PPR (Next 15) |
| Pure SPA | 매 Next 대신 Vite + React |

**기본값**: App Router + RSC + PPR. Pages Router 는 매 legacy.

## 🔗 Graph
- 부모: [[React]]
- 변형: [[Remix]] · [[Astro]] · [[SvelteKit]]
- Adjacent: [[React Server Components]] · [[Turbopack]] · [[Edge Runtime]]

## 🤖 LLM 활용
**언제**: App Router migration, RSC 설계, Server Action 구현, PPR 적용.
**언제 X**: 매 pure backend (Express/Fastify), pure SPA.

## ❌ 안티패턴
- **`"use client"` on root layout**: 매 RSC 효과 무효 — 매 leaf 만.
- **`fetch` 안에 secret**: 매 client 로 leak 가능 — 매 Server Action 사용.
- **getInitialProps**: 매 Pages Router legacy — 매 App Router 에서 X.
- **Massive client bundle**: 매 Server Component 로 옮길 것.

## 🧪 검증 / 중복
- Verified (nextjs.org docs, React 19 RSC spec).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — Next 15 RSC + PPR + Server Action |