03: Next.js는 왜 다른가 — "빌드 결과가 파일이 아니라 애플리케이션이다"

$ cd my-react-app
$ npm run build
 
$ ls dist/
index.html            # 진입점 HTML
assets/
  index-CdTgQbWo.js   # JS 번들
  index-DiwrgTda.css   # CSS
 
$ du -sh dist/
  1.2M  dist/

빌드 결과 = 정적 파일들
→ 어떤 서버든 서빙 가능 (Flask, Nginx, CDN, GitHub Pages)
→ 서버는 "파일을 전달"하기만 하면 됨
→ Node.js 필요 없음!

$ cd my-nextjs-app
$ npm run build
 
$ ls -la
.next/                 # ← 이게 빌드 결과물
  server/              # 서버 사이드 코드
    app/
      page.js          # 서버에서 실행되는 페이지 코드
      api/
        route.js       # API 라우트 코드
    chunks/            # 서버 청크
  static/              # 정적 에셋
    chunks/
      app/
        page-abc123.js # 클라이언트 JS
    css/
      app/layout.css   # CSS
  cache/               # 빌드 캐시
    fetch-cache/
    images/
 
$ du -sh .next/
  45M  .next/

# React: 그냥 파일 → 아무 서버로 서빙
$ nginx -c /etc/nginx/nginx.conf  # Nginx로 서빙 가능
$ python -m http.server 8000      # Python으로 서빙 가능
 
# Next.js: 애플리케이션 → Node.js 서버 필요
$ next start                       # Node.js 서버로 실행해야 함
$ node server.js                   # 또는 커스텀 Node.js 서버

┌───────────────────────────────────────────────────────────────┐
│                                                                 │
│   순수 React (Vite) 빌드 결과 = "파일"                         │
│   ─────────────────────────────────────                         │
│   • HTML + JS + CSS 정적 파일                                  │
│   • 어떤 웹 서버에서든 서빙 가능                               │
│   • 서버는 "택배 기사" — 파일을 전달만 함                      │
│                                                                 │
│   Next.js 빌드 결과 = "애플리케이션"                           │
│   ─────────────────────────────────────                         │
│   • 서버 코드 + 클라이언트 코드 + 캐시 + 설정                 │
│   • Node.js 런타임에서 실행해야 함                              │
│   • 서버는 "요리사" — 매 요청마다 HTML을 만듦                  │
│                                                                 │
└───────────────────────────────────────────────────────────────┘

매 요청마다 서버에서 HTML을 새로 생성

// app/products/[id]/page.tsx
export default async function ProductPage({ params }: { params: { id: string } }) {
  // 서버에서 실행됨 — 매 요청마다!
  const product = await db.query('SELECT * FROM products WHERE id = $1', [params.id]);
 
  return (
    <div>
      <h1>{product.name}</h1>
      <p>가격: {product.price}원</p>
      <p>재고: {product.stock}개</p>  {/* 실시간 재고 */}
    </div>
  );
}

서버에서 API 엔드포인트 실행

// app/api/users/route.ts
import { NextResponse } from 'next/server';
 
export async function GET() {
  // 서버에서 실행됨
  const users = await db.query('SELECT * FROM users');
  return NextResponse.json(users);
}
 
export async function POST(request: Request) {
  // 서버에서 실행됨
  const body = await request.json();
  await db.query('INSERT INTO users (name) VALUES ($1)', [body.name]);
  return NextResponse.json({ success: true });
}

정적 페이지를 주기적으로 서버에서 재생성

// app/blog/[slug]/page.tsx
export const revalidate = 60;  // 60초마다 재생성
 
export default async function BlogPost({ params }: { params: { slug: string } }) {
  // 빌드 시 + 60초마다 서버에서 실행
  const post = await fetch(`https://cms.example.com/posts/${params.slug}`);
  const data = await post.json();
 
  return (
    <article>
      <h1>{data.title}</h1>
      <div>{data.content}</div>
    </article>
  );
}

요청이 페이지에 도달하기 전에 서버에서 가로채기

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
 
export function middleware(request: NextRequest) {
  // 모든 요청에 대해 서버에서 실행됨
  const token = request.cookies.get('auth-token');
 
  // 로그인 안 했으면 로그인 페이지로 리다이렉트
  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
 
  // A/B 테스트
  const bucket = Math.random() > 0.5 ? 'a' : 'b';
  const response = NextResponse.next();
  response.cookies.set('ab-test', bucket);
  return response;
}

컴포넌트 자체가 서버에서만 실행

// app/dashboard/page.tsx — Server Component (기본값)
// 이 컴포넌트는 서버에서만 실행됨. 브라우저에 JS가 전송되지 않음!
 
import { headers } from 'next/headers';
 
export default async function Dashboard() {
  const headersList = await headers();
  const userId = headersList.get('x-user-id');
 
  // 서버에서 직접 DB 조회 — 브라우저에 노출 안 됨!
  const data = await db.query('SELECT * FROM dashboard WHERE user_id = $1', [userId]);
 
  // 비밀 API 키도 안전하게 사용 가능
  const analytics = await fetch('https://api.analytics.com/data', {
    headers: { 'Authorization': `Bearer ${process.env.SECRET_API_KEY}` }
  });
 
  return (
    <div>
      <h1>대시보드</h1>
      <p>방문자: {data.visitors}</p>
      <p>매출: {data.revenue}원</p>
    </div>
  );
}
// → 이 컴포넌트의 JS는 브라우저에 전송되지 않음 (번들 크기 0!)

// next.config.js
const nextConfig = {
  output: 'export',  // 정적 빌드 모드
};
 
export default nextConfig;

$ npm run build
 
# 이번에는 out/ 폴더에 정적 파일이 생성됨
$ ls out/
index.html
about.html
products/
  1.html
  2.html
_next/
  static/
    chunks/...
    css/...

┌─────────────────────────────────────────────────────────────┐
│          output: 'export' 사용 시 포기하는 것들              │
│                                                               │
│  ❌ SSR (Server-Side Rendering)                              │
│     → 매 요청마다 HTML 생성 불가                             │
│                                                               │
│  ❌ API Routes                                               │
│     → 서버 API 엔드포인트 사용 불가                          │
│                                                               │
│  ❌ ISR (Incremental Static Regeneration)                    │
│     → 주기적 재생성 불가                                     │
│                                                               │
│  ❌ Middleware                                               │
│     → 요청 가로채기 불가                                     │
│                                                               │
│  ❌ Server Components (동적)                                 │
│     → 서버 전용 컴포넌트 사용 불가                           │
│                                                               │
│  ❌ Dynamic Routes (동적 params)                             │
│     → generateStaticParams 필수                              │
│                                                               │
│  ✅ 사용 가능한 것                                           │
│     → 정적 페이지, 클라이언트 컴포넌트, 정적 생성(SSG)      │
│                                                               │
└─────────────────────────────────────────────────────────────┘

Next.js + output: 'export'   → 핵심 기능 포기, 빌드 느림, 복잡
Vite + React                  → 같은 결과, 빌드 빠름, 단순
 
→ 정적 빌드만 할 거면 Vite를 쓰는 게 낫다

┌────────────────────────────────────────────────────────────────┐
│                     리버스 프록시 (Nginx)                       │
│                                                                  │
│   브라우저 ──→ Nginx (포트 80)                                  │
│                  │                                               │
│                  ├── /api/*    ──→ Flask (포트 5000)             │
│                  │                  Python 백엔드                │
│                  │                  DB 접근, 비즈니스 로직       │
│                  │                                               │
│                  └── /*       ──→ Next.js (포트 3000)            │
│                                    Node.js 서버                  │
│                                    SSR, 프론트엔드               │
└────────────────────────────────────────────────────────────────┘

# nginx.conf
server {
    listen 80;
 
    # API 요청 → Flask
    location /api/ {
        proxy_pass http://localhost:5000;
    }
 
    # 나머지 → Next.js
    location / {
        proxy_pass http://localhost:3000;
    }
}

Flask 백엔드를 이미 쓰고 있다면:
├── SSR 필요 없음 → Flask + React/Svelte 정적 빌드 (01편 방식)
├── SSR 필요 + 새 프로젝트 → Next.js 단독 (Flask 제거)
└── SSR 필요 + Flask 유지 필수 → Flask + Next.js + Nginx (복잡)

출판사(빌드) → 책(정적 파일) → 서점(웹 서버) → 독자(브라우저)
 
• 책은 한번 인쇄하면 내용이 바뀌지 않음
• 어떤 서점에서든 팔 수 있음 (Flask, Nginx, CDN)
• 서점은 책 내용을 모름 — 그냥 전달만 함

요리학교(빌드) → 요리사+레시피(.next/) → 레스토랑(Node.js) → 손님(브라우저)
 
• 손님이 주문할 때마다 요리를 새로 만듦 (SSR)
• 요리사가 없으면 레시피만으로는 요리 불가 (Node.js 필수)
• 레스토랑이 필요함 — 서점에서는 안 됨 (Nginx만으로 안 됨)

┌─────────────────────────────────────────────────────────────┐
│                                                               │
│   "React 빌드 결과는 파일이고,                               │
│    Next.js 빌드 결과는 애플리케이션이다."                     │
│                                                               │
│   파일은 어디서든 서빙 가능하고,                              │
│   애플리케이션은 실행 환경이 필요하다.                        │
│                                                               │
└─────────────────────────────────────────────────────────────┘