✍️ 필사 모드: React Server Components & Next.js App Router Deep Dive — RSC, Streaming, Cache, Server Actions 완전 정복 (2025)

[Server]                [Client]
HTML 응답 (빈 페이지)  →  JS 다운로드 → React 실행 → DOM 생성

[Server]                [Client]
React → HTML 생성      → HTML 다운로드 (즉시 보임)
                       → JS 다운로드
                       → Hydration (이벤트 연결)

// app/page.jsx
// 기본: 서버 컴포넌트

import db from '@/lib/db';

export default async function HomePage() {
  const posts = await db.posts.findMany();
  
  return (
    <div>
      <h1>Posts</h1>
      {posts.map(post => (
        <article key={post.id}>
          <h2>{post.title}</h2>
          <p>{post.excerpt}</p>
        </article>
      ))}
    </div>
  );
}

// app/components/LikeButton.jsx
"use client";

import { useState } from 'react';

export default function LikeButton({ postId }) {
  const [liked, setLiked] = useState(false);
  
  return (
    <button onClick={() => setLiked(!liked)}>
      {liked ? '❤️' : '🤍'}
    </button>
  );
}

// app/page.jsx (서버)
import db from '@/lib/db';
import LikeButton from './components/LikeButton';  // 클라이언트 컴포넌트

export default async function HomePage() {
  const posts = await db.posts.findMany();
  
  return (
    <div>
      {posts.map(post => (
        <article key={post.id}>
          <h2>{post.title}</h2>
          <LikeButton postId={post.id} />  {/* 클라이언트 컴포넌트 */}
        </article>
      ))}
    </div>
  );
}

// Button.jsx
"use client";

import { useState } from 'react';
import MyComponent from './MyComponent';  // 이 파일은 자동으로 client
import { helper } from './utils';          // helper도 client에 포함

// 서버
<LikeButton postId={post.id} userId={user.id} />

1:D{"type":"article","props":{...},"children":[...]}
2:{"type":"$L3","props":{"postId":"abc"}}
3:I["./LikeButton.js","LikeButton"]
...

서버 시작
→ [첫 chunk 전송] Header 컴포넌트 렌더링 완료
→ [두 번째 chunk] 메인 콘텐츠 일부
→ [세 번째 chunk] 느린 데이터 (await)
→ [완료]

<LikeButton postId="abc" />

import { Suspense } from 'react';

export default async function Page() {
  return (
    <div>
      <Header />
      <Suspense fallback={<Loading />}>
        <SlowComponent />
      </Suspense>
    </div>
  );
}

async function SlowComponent() {
  await new Promise(r => setTimeout(r, 3000));  // 느린 데이터
  return <div>Loaded!</div>;
}

<Suspense fallback={<PostsLoading />}>
  <Posts />  {/* 2초 */}
</Suspense>
<Suspense fallback={<UsersLoading />}>
  <Users />  {/* 1초 */}
</Suspense>

// Client component
"use client";

import { use } from 'react';

function PostContent({ postPromise }) {
  const post = use(postPromise);  // Suspense throw
  return <h1>{post.title}</h1>;
}

app/
├── layout.tsx
├── page.tsx
└── loading.tsx   ← 자동 Suspense boundary

// app/actions.ts
"use server";

import { revalidatePath } from 'next/cache';

export async function createPost(formData: FormData) {
  const title = formData.get('title');
  await db.posts.create({ data: { title } });
  revalidatePath('/posts');
}

// app/posts/new/page.tsx
import { createPost } from '@/app/actions';

export default function NewPostPage() {
  return (
    <form action={createPost}>
      <input name="title" />
      <button type="submit">Create</button>
    </form>
  );
}

"use client";
import { useOptimistic } from 'react';

function PostList({ posts }) {
  const [optimisticPosts, addOptimisticPost] = useOptimistic(
    posts,
    (state, newPost) => [...state, newPost]
  );

  async function action(formData) {
    addOptimisticPost({ title: formData.get('title'), pending: true });
    await createPost(formData);  // server action
  }

  return (
    <>
      <form action={action}>
        <input name="title" />
        <button>Submit</button>
      </form>
      {optimisticPosts.map(post => (
        <div style={{ opacity: post.pending ? 0.5 : 1 }}>{post.title}</div>
      ))}
    </>
  );
}

app/
├── layout.tsx          ← 루트 레이아웃
├── page.tsx            ← "/" 페이지
├── globals.css
├── about/
│   └── page.tsx        ← "/about"
├── blog/
│   ├── layout.tsx      ← /blog 하위의 레이아웃
│   ├── page.tsx        ← "/blog"
│   ├── loading.tsx     ← /blog 로딩 상태
│   ├── error.tsx       ← /blog 에러 boundary
│   └── [slug]/
│       └── page.tsx    ← "/blog/my-post"
└── api/
    └── posts/
        └── route.ts    ← "/api/posts" handler

// app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Header />
        {children}
        <Footer />
      </body>
    </html>
  );
}

// app/blog/layout.tsx
export default function BlogLayout({ children }) {
  return (
    <div className="blog">
      <BlogSidebar />
      {children}
    </div>
  );
}

// app/blog/[slug]/page.tsx
export default function BlogPost() {
  return <article>...</article>;
}

RootLayout
  Header
  BlogLayout
    BlogSidebar
    BlogPost
  Footer

// app/blog/[slug]/page.tsx
export default function Page({ params }) {
  return <div>Post: {params.slug}</div>;
}

app/
├── (marketing)/
│   ├── layout.tsx
│   ├── page.tsx        ← "/"
│   └── about/
│       └── page.tsx    ← "/about"
├── (app)/
│   ├── layout.tsx
│   ├── dashboard/
│   │   └── page.tsx    ← "/dashboard"
│   └── settings/
│       └── page.tsx    ← "/settings"

app/
├── @team/
│   └── page.tsx
├── @analytics/
│   └── page.tsx
└── layout.tsx

// app/layout.tsx
export default function Layout({ children, team, analytics }) {
  return (
    <div>
      {children}
      <aside>{team}</aside>
      <section>{analytics}</section>
    </div>
  );
}

app/
├── feed/
│   ├── page.tsx
│   └── @modal/
│       └── (...)photo/
│           └── [id]/
│               └── page.tsx
├── photo/
│   └── [id]/
│       └── page.tsx

// layout.tsx
const user = await fetch('/api/user');

// page.tsx (같은 요청)
const user = await fetch('/api/user');  // 캐시에서 반환

// 기본: 영구 캐시
const data = await fetch('https://api.example.com/data');

// 재검증 옵션
const data = await fetch(url, { next: { revalidate: 60 } });  // 60초 후 stale

// 캐시 안 함
const data = await fetch(url, { cache: 'no-store' });

// 태그
const data = await fetch(url, { next: { tags: ['posts'] } });

Build time:
  /blog/post-a → HTML + RSC payload 저장
  /blog/post-b → HTML + RSC payload 저장

Runtime:
  GET /blog/post-a → 캐시된 HTML 즉시 반환

/a 방문 → /a의 RSC 저장
/b 방문 → /b의 RSC 저장
/a로 back → 캐시된 /a 사용 (network 안 함)

// 10분마다
export const revalidate = 600;

import { revalidatePath } from 'next/cache';

export async function createPost() {
  // ...
  revalidatePath('/blog');
}

fetch(url, { next: { tags: ['posts'] } });

import { revalidateTag } from 'next/cache';
revalidateTag('posts');

export default async function Page() {
  const data = await fetch('https://api.example.com/data');
  return <div>{data.title}</div>;
}

import { cookies } from 'next/headers';

export default async function Page() {
  const cookieStore = cookies();
  const theme = cookieStore.get('theme');
  // ...
}

export const dynamic = 'force-dynamic';

export const dynamic = 'force-static';

export default function Page() {
  return (
    <div>
      <StaticHeader />  {/* static, 즉시 */}
      <Suspense fallback={<Spinner />}>
        <DynamicContent />  {/* dynamic, 스트리밍 */}
      </Suspense>
    </div>
  );
}

// middleware.js
import { NextResponse } from 'next/server';

export function middleware(request) {
  const auth = request.cookies.get('auth');
  
  if (!auth && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
  
  return NextResponse.next();
}

export const config = {
  matcher: ['/dashboard/:path*', '/api/:path*'],
};

export const config = {
  matcher: [
    '/((?!api|_next/static|_next/image|favicon.ico).*)',
  ],
};

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

export async function GET(request: Request) {
  const posts = await db.posts.findMany();
  return NextResponse.json(posts);
}

export async function POST(request: Request) {
  const body = await request.json();
  const post = await db.posts.create({ data: body });
  return NextResponse.json(post, { status: 201 });
}

export async function GET() {
  const stream = new ReadableStream({
    async start(controller) {
      for (let i = 0; i < 10; i++) {
        controller.enqueue(`Chunk ${i}\n`);
        await new Promise(r => setTimeout(r, 500));
      }
      controller.close();
    },
  });
  return new Response(stream);
}

// 페이지 레벨
export const runtime = 'edge';  // 또는 'nodejs'

// next.config.js
module.exports = {
  output: 'export',
};

import Image from 'next/image';

<Image
  src="/photo.jpg"
  alt="Photo"
  width={500}
  height={300}
  priority
/>

import { Inter } from 'next/font/google';

const inter = Inter({ subsets: ['latin'] });

export default function Layout({ children }) {
  return (
    <html className={inter.className}>
      <body>{children}</body>
    </html>
  );
}

pages/
├── index.tsx     ← 기존 pages router
└── api/
    └── hello.ts

app/
├── dashboard/
│   └── page.tsx  ← 새 app router

export async function getServerSideProps() {
  const data = await fetch(...);
  return { props: { data } };
}

export default function Page({ data }) {
  return <div>{data}</div>;
}

export default async function Page() {
  const data = await fetch(...);
  return <div>{data}</div>;
}

<ClientComponent 
  onClick={() => console.log('hi')}  // 함수 직렬화 불가!
/>

// BAD
<div>{new Date().toLocaleString()}</div>

DATABASE_URL=...              # 서버 only
NEXT_PUBLIC_API_URL=...       # 클라이언트도

┌─────────────────────────────────────────────────────┐
│        RSC & Next.js App Router Cheat Sheet         │
├─────────────────────────────────────────────────────┤
│ RSC 기본:                                              │
│   Server Components: 서버에서만, async 가능          │
│   Client Components: "use client", 기존 React       │
│   Props는 서버 → 클라이언트 직렬화                     │
│                                                       │
│ "use client":                                         │
│   파일 최상단 지시어                                    │
│   네트워크 경계                                        │
│   이 아래 모듈은 클라이언트 번들                        │
│                                                       │
│ Streaming:                                            │
│   Suspense boundary                                   │
│   RSC payload 점진적 전송                              │
│   loading.tsx 자동 Suspense                           │
│                                                       │
│ Server Actions:                                       │
│   "use server" 함수                                    │
│   <form action={fn}>                                  │
│   자동 RPC                                             │
│   revalidatePath/revalidateTag                       │
│   useOptimistic                                       │
│                                                       │
│ App Router 파일:                                       │
│   page.tsx        라우트 컴포넌트                     │
│   layout.tsx      중첩 레이아웃                        │
│   loading.tsx     Suspense fallback                  │
│   error.tsx       Error boundary                     │
│   not-found.tsx   404                                │
│   route.ts        API handler                        │
│   middleware.ts   요청 전 처리                         │
│                                                       │
│ Advanced Routes:                                      │
│   [slug]          dynamic                            │
│   [...slug]       catch-all                          │
│   (group)         route group                        │
│   @modal          parallel route                     │
│   (...)photo      intercepting route                 │
│                                                       │
│ 캐시 4층:                                              │
│   1. Request Memoization (per request)              │
│   2. Data Cache (fetch level)                        │
│   3. Full Route Cache (build)                        │
│   4. Router Cache (client nav)                       │
│                                                       │
│ Rendering:                                            │
│   Static (기본)                                       │
│   Dynamic (cookies/headers/searchParams)             │
│   Streaming (Suspense)                                │
│   PPR (experimental)                                  │
│                                                       │
│ Runtime:                                              │
│   Node.js (기본, 완전 API)                            │
│   Edge (빠른 cold start, 제한)                        │
│                                                       │
│ Turbopack:                                            │
│   Rust 기반 번들러                                     │
│   10-20x Webpack                                      │
│   Dev 안정, Build 안정화 중                            │
│                                                       │
│ 함정:                                                  │
│   "use client" 남용                                    │
│   Context 제한                                         │
│   직렬화 불가 props                                     │
│   Hydration mismatch                                  │
│   Env var 경계 (NEXT_PUBLIC_)                         │
└─────────────────────────────────────────────────────┘