
## 데이터 캐시란


App Router의 데이터 캐시는 서버에서 가져온 데이터를 저장하고 재사용하는 메커니즘이다. 동일한 데이터를 반복해서 외부 API나 데이터베이스에서 가져오는 대신, 한 번 가져온 데이터를 서버 메모리에 저장해두고 다음 요청에서 빠르게 응답할 수 있다.


데이터 캐시를 사용하려면 `fetch` API를 사용해야 한다. Next.js는 Web API의 표준 fetch를 확장하여 다양한 캐싱 옵션을 제공한다.


## fetch API와 캐싱 옵션


Next.js의 fetch는 `cache`와 `next` 옵션을 통해 캐싱 동작을 제어할 수 있다.


```javascript
// 기본 사용법
const res = await fetch('<https://api.example.com/data>', {
  cache: 'force-cache',  // 캐싱 전략
  next: {
    revalidate: 60,  // 재검증 주기
    tags: ['posts']  // 캐시 태그
  }
});
```


각 옵션은 데이터의 특성과 업데이트 빈도에 따라 선택한다.


## no-store - 캐싱 비활성화


데이터 페칭 결과를 저장하지 않는다. 매 요청마다 서버에서 새로운 데이터를 가져온다.


```javascript
async function RealTimePrice() {
  const res = await fetch('<https://api.example.com/stock-price>', {
    cache: 'no-store'
  });
  const data = await res.json();

  return <div>현재 가격: {data.price}원</div>;
}
```


Next.js 서버가 브라우저로부터 접속 요청을 받으면 사전 렌더링을 진행하게 되는데, `no-store`로 설정된 fetch는 캐시를 무시하고 바로 원본 서버로 요청을 보낸 뒤 브라우저에 응답한다.


Next.js 15부터는 data cache의 기본값이 `no-store`로 변경되었다. 이전 버전에서는 `force-cache`가 기본값이었지만, 최신 데이터를 제공하는 것이 더 중요하다는 판단에 따라 기본 동작이 바뀌었다.


### 사용 시나리오

- 실시간 주식 가격, 환율 정보
- 사용자별로 다른 데이터 (개인화된 콘텐츠)
- 자주 변경되는 데이터 (뉴스, 댓글)

## force-cache - 영구 캐싱


요청의 결과를 무조건 캐싱한다. 한 번 호출된 이후에는 재배포하거나 수동으로 캐시를 초기화하기 전까지 다시 호출되지 않는다.


```javascript
async function StaticContent() {
  const res = await fetch('<https://api.example.com/terms>', {
    cache: 'force-cache'
  });
  const data = await res.json();

  return <div>{data.content}</div>;
}
```


첫 번째 요청에서는 cache miss가 발생하지만, 서버에서 데이터를 가져온 후 캐시에 저장(set)한다. 두 번째 요청부터는 cache hit이 발생하여 캐시된 데이터를 즉시 반환한다.


```plain text
1번째 요청: Miss → 서버 요청 → Set (캐시 저장)
2번째 요청: Hit → 캐시된 데이터 반환
3번째 요청: Hit → 캐시된 데이터 반환
```


### 사용 시나리오

- 거의 변경되지 않는 데이터 (이용약관, 회사 소개)
- 정적 콘텐츠 (블로그 글, 제품 설명)
- 외부 API 호출 비용이 높은 경우

## revalidate - 주기적 재검증


특정 시간을 주기로 캐시를 업데이트한다. [[사전 렌더링 방식 - SSR, SSG, ISR|Page Router의 ISR 방식]]과 유사하게 동작한다.


```javascript
async function ProductList() {
  const res = await fetch('<https://api.example.com/products>', {
    next: { revalidate: 3600 }  // 1시간마다 재검증
  });
  const products = await res.json();

  return (
    <ul>
      {products.map(p => <li key={p.id}>{p.name}</li>)}
    </ul>
  );
}
```


동작 과정은 다음과 같다.


```plain text
0초: 첫 요청 → 서버 요청 → 캐시 저장 (fresh)
30초: 두 번째 요청 → 캐시 반환 (fresh)
3600초: 캐시가 stale로 변경
3601초: 요청 → 캐시 반환 (stale) + 백그라운드에서 재검증 시작
3605초: 재검증 완료 → 캐시 업데이트 (fresh)
3610초: 요청 → 새로운 캐시 반환 (fresh)
```


정해진 주기(`revalidate` 시간)가 지나면 캐시가 stale 상태가 된다. 이 상태에서 요청이 들어오면 일단 오래된 캐시를 반환하고, 백그라운드에서 데이터를 새로 가져온다. 다음 요청부터는 업데이트된 데이터를 받을 수 있다.


### 사용 시나리오

- 자주는 아니지만 가끔 업데이트되는 데이터 (제품 목록, 카테고리)
- 실시간성이 중요하지 않은 데이터 (통계, 인기 게시물)
- 외부 API 호출을 줄이면서도 적절한 최신성을 유지하고 싶을 때

## tags - 온디맨드 재검증


캐시에 태그를 붙여서 원하는 시점에 특정 태그의 캐시를 업데이트할 수 있다.


```javascript
// 데이터 페칭
async function BlogPost({ id }) {
  const res = await fetch(`https://api.example.com/posts/${id}`, {
    next: { tags: ['posts', `post-${id}`] }
  });
  const post = await res.json();

  return <article>{post.content}</article>;
}
```


위 코드에서 fetch 요청에 `tags: ['posts', 'post-${id}']`를 지정했다. 이제 다른 곳에서 캐시를 수동으로 무효화할 수 있다.


```javascript
// app/api/revalidate/route.js
import { revalidateTag } from 'next/cache';

export async function POST(request) {
  const { tag } = await request.json();

  revalidateTag(tag);  // 특정 태그의 캐시 무효화

  return Response.json({ revalidated: true });
}
```


`revalidateTag('posts')`를 호출하면 'posts' 태그가 붙은 모든 캐시가 즉시 무효화되고, 다음 요청에서 새로운 데이터를 가져온다.


### 사용 시나리오

- CMS에서 콘텐츠 수정 후 즉시 반영
- 관리자가 제품 정보를 업데이트한 경우
- 사용자가 댓글을 작성한 직후
- Webhook을 통해 외부 시스템 변경 감지

### revalidatePath와의 차이


```javascript
import { revalidatePath } from 'next/cache';

// 특정 경로의 캐시 무효화
revalidatePath('/blog/post-1');

// 특정 태그의 캐시 무효화 (더 세밀한 제어)
revalidateTag('post-1');
```


`revalidatePath`는 페이지 단위로 캐시를 무효화하는 반면, `revalidateTag`는 fetch 요청 단위로 더 세밀하게 제어할 수 있다. 하나의 페이지에 여러 fetch 요청이 있을 때 특정 요청만 선택적으로 무효화하려면 태그를 사용한다.


## 실전 활용 패턴


### 페이지별로 다른 전략 사용


```javascript
// 홈페이지 - 자주 변경되는 데이터
async function HomePage() {
  const news = await fetch('/api/news', { cache: 'no-store' });
  const popular = await fetch('/api/popular', { next: { revalidate: 300 } });

  return (
    <div>
      <NewsList data={news} />
      <PopularPosts data={popular} />
    </div>
  );
}
```


하나의 페이지에서도 데이터의 특성에 따라 다른 캐싱 전략을 조합할 수 있다. 실시간 뉴스는 `no-store`로 매번 새로 가져오고, 인기 게시물은 5분마다 업데이트한다.


### 캐시 전략 선택 가이드


```plain text
데이터 변경 빈도 및 중요도에 따른 선택

실시간 필수 → no-store
거의 변경 안됨 → force-cache
주기적 업데이트 → revalidate (시간 지정)
이벤트 기반 업데이트 → tags + revalidateTag
```


캐싱은 성능과 최신성 사이의 트레이드오프다. 데이터의 특성과 사용자 경험을 고려하여 적절한 전략을 선택해야 한다.



Data Cache

App Router 데이터 캐시


## React Server Component란


React Server Component(RSC)는 서버에서 렌더링되는 React 컴포넌트다. Next.js App Router는 기본적으로 모든 컴포넌트를 Server Component로 취급한다.


기존 React 앱은 모든 컴포넌트가 브라우저에서 실행되었다. Server Component는 서버에서 렌더링을 완료한 뒤 결과만 클라이언트로 보낸다. 이를 통해 JavaScript 번들 크기를 줄이고 초기 로딩 속도를 개선할 수 있다.


## 왜 필요한가


기존 React 앱에서는 데이터를 가져오기 위해 다음과 같은 과정을 거친다.

1. 브라우저가 빈 HTML을 받는다
2. JavaScript 번들을 다운로드하고 실행한다
3. 컴포넌트가 마운트되면 `useEffect`로 API를 호출한다
4. 데이터를 받아서 화면을 업데이트한다

이 과정에서 사용자는 로딩 상태를 보게 되고, JavaScript 번들 크기가 커질수록 초기 로딩이 느려진다.


Server Component는 이 문제를 해결한다. 서버에서 데이터를 가져오고 렌더링까지 완료한 뒤 결과만 보내므로, 브라우저는 즉시 컨텐츠를 표시할 수 있다.


## Server Component의 장점


Server Component는 다음과 같은 장점을 제공한다.

- 데이터 소스에 가까운 위치에서 데이터를 가져온다. 서버는 데이터베이스나 내부 API와 같은 네트워크에 있으므로 데이터 조회가 빠르다.
- **클라이언트로 전송하는 JavaScript 크기를 줄인다.** 서버에서만 실행되는 코드는 브라우저로 보내지 않는다.
- 초기 페이지 로딩이 빠르다. HTML이 서버에서 생성되어 오므로 First Contentful Paint가 개선된다.
- 보안이 강화된다. API 키나 토큰 같은 민감한 정보를 서버에만 두고 사용할 수 있다.

## Server Component의 특징


Server Component에서는 다음과 같은 작업을 할 수 있다.


```typescript
import { db } from '@/lib/database'

export default async function ProductList() {
  // 데이터베이스 직접 조회
  const products = await db.query('SELECT * FROM products')

  return (
    <ul>
      {products.map(product => (
        <li key={product.id}>{product.name}</li>
      ))}
    </ul>
  )
}
```


위 코드에서 컴포넌트를 `async` 함수로 선언하고 데이터베이스를 직접 조회한다. 이 코드는 서버에서만 실행되므로 데이터베이스 연결 정보가 클라이언트에 노출되지 않는다.


Server Component는 컴포넌트 함수 자체를 `async`로 만들 수 있다. 별도의 데이터 페칭 함수 없이 컴포넌트 내부에서 바로 비동기 작업을 수행할 수 있다.


## Server Component의 제약사항


Server Component는 서버에서만 실행되기 때문에 클라이언트 전용 기능을 사용할 수 없다. 다음과 같은 것들은 Server Component에서 사용할 수 없다.

- 상태 관리 훅: `useState`, `useReducer`
- 생명주기 훅: `useEffect`, `useLayoutEffect`
- 이벤트 핸들러: `onClick`, `onChange`
- 브라우저 전용 API: `window`, `localStorage`, `document`
- 사용자 정의 훅: 위 기능들을 사용하는 커스텀 훅
- React Context: `useContext`

예를 들어 Server Component에서 `useEffect`를 사용하려고 하면 다음과 같은 에러가 발생한다.


```plain text
Error: useEffect only works in Client Components. Add the "use client" directive at the top of the file to use it.
```


이런 기능이 필요하다면 해당 컴포넌트를 Client Component로 만들어야 한다. 파일 최상단에 `'use client'`를 추가하면 된다.


```typescript
// 에러 발생
export default function ProductList() {
  useEffect(() => {
    console.log('마운트됨')
  }, [])

  return <div>상품 목록</div>
}
```


```typescript
// ✓ 정상 작동
'use client'

export default function ProductList() {
  useEffect(() => {
    console.log('마운트됨')
  }, [])

  return <div>상품 목록</div>
}
```


Server Component는 HTML을 생성하는 데 집중하고, 인터랙션이 필요한 부분은 Client Component로 분리하는 것이 권장된다.


## Client Component란


하지만 모든 것을 Server Component로 만들 수는 없다. 사용자와의 상호작용, 상태 관리, 브라우저 API 사용 등은 클라이언트에서만 가능하다.


Client Component는 브라우저에서 실행되는 React 컴포넌트다. 다음과 같은 기능을 사용할 때는 Client Component가 필요하다.

- `useState`, `useReducer` 같은 상태 관리
- `useEffect`, `useLayoutEffect` 같은 생명주기 훅
- `onClick`, `onChange` 같은 이벤트 핸들러
- `window`, `localStorage` 같은 브라우저 전용 API
- 사용자 정의 훅

## 'use client' 디렉티브


Client Component를 만들려면 파일 최상단에 `'use client'` 디렉티브를 추가한다.


```typescript
'use client'

import { useState } from 'react'

export default function LikeButton() {
  const [likes, setLikes] = useState(0)

  return (
    <button onClick={() => setLikes(likes + 1)}>
      좋아요 {likes}
    </button>
  )
}
```


`'use client'`는 서버와 클라이언트 코드 사이의 경계를 선언한다. 이 디렉티브가 있는 파일과 그 파일이 import하는 모든 모듈은 클라이언트 번들에 포함된다.


`'use client'`를 추가하지 않으면 기본적으로 Server Component로 동작한다. Next.js App Router는 Server Component를 기본값으로 사용한다.


## 언제 무엇을 사용할지


다음 표는 어떤 상황에 어떤 컴포넌트를 사용해야 하는지 정리한 것이다.


| 작업                               | Server Component | Client Component |
| -------------------------------- | ---------------- | ---------------- |
| 데이터 가져오기                         | ✓                |                  |
| 백엔드 리소스 직접 접근                    | ✓                |                  |
| 민감한 정보를 서버에 보관                   | ✓                |                  |
| 큰 의존성을 서버에 유지                    | ✓                |                  |
| 상태 관리 (`useState`, `useReducer`) |                  | ✓                |
| 생명주기 훅 (`useEffect`)             |                  | ✓                |
| 이벤트 핸들러                          |                  | ✓                |
| 브라우저 전용 API                      |                  | ✓                |
| 사용자 정의 훅                         |                  | ✓                |


기본적으로 Server Component를 사용하고, 인터랙션이 필요한 부분만 Client Component로 분리하는 것이 권장된다.


## Server Component와 Client Component 조합하기


Server Component와 Client Component는 함께 사용할 수 있다.


### Server Component에서 Client Component로 데이터 전달하기


Server Component는 Client Component에 props로 데이터를 전달할 수 있다. 단, props는 직렬화 가능한 값이어야 한다.


```typescript
// app/page.tsx (Server Component)
import LikeButton from './like-button'

export default async function PostPage({ params }) {
  const post = await getPost(params.id)

  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
      <LikeButton initialLikes={post.likes} />
    </article>
  )
}
```


```typescript
// app/like-button.tsx (Client Component)
'use client'

import { useState } from 'react'

export default function LikeButton({ initialLikes }) {
  const [likes, setLikes] = useState(initialLikes)

  return (
    <button onClick={() => setLikes(likes + 1)}>
      좋아요 {likes}
    </button>
  )
}
```


위 코드에서 Server Component인 `PostPage`는 서버에서 포스트 데이터를 가져온다. 그리고 초기 좋아요 수를 `LikeButton`에 전달한다. `LikeButton`은 Client Component이므로 브라우저에서 상태를 관리하며 사용자의 클릭에 반응한다.


### Client Component 안에 Server Component 넣기


Client Component는 직접적으로 Server Component를 import할 수 없다. 하지만 `children` prop을 통해 Server Component를 받을 수 있다.


```typescript
// app/modal.tsx (Client Component)
'use client'

export default function Modal({ children }) {
  return (
    <div className="modal">
      {children}
    </div>
  )
}
```


```typescript
// app/page.tsx (Server Component)
import Modal from './modal'
import ServerContent from './server-content'

export default function Page() {
  return (
    <Modal>
      <ServerContent />
    </Modal>
  )
}
```


위 패턴에서 `Modal`은 Client Component지만 `children`으로 무엇을 받을지는 모른다. `ServerContent`는 Server Component로서 서버에서 렌더링된다. `Modal`은 단지 렌더링된 결과를 받아서 표시할 뿐이다.


이 패턴을 사용하면 Client Component와 Server Component를 독립적으로 렌더링할 수 있다. Client Component가 재렌더링되어도 Server Component는 서버에서 이미 렌더링되었기 때문에 다시 렌더링되지 않는다.


## 주의사항


### Client Component는 양쪽에서 실행된다


Server Component는 서버에서만 실행되지만, Client Component는 서버와 클라이언트 양쪽에서 실행된다.

- 서버: 초기 HTML 생성(사전 렌더링)을 위해 1번 실행
- 클라이언트: 하이드레이션을 위해 1번 실행

따라서 Client Component에는 브라우저 전용 API(`window`, `localStorage` 등)를 바로 사용하면 안 된다. 서버에서 실행될 때 에러가 발생한다. `useEffect` 안에서 사용하거나 조건부로 체크해야 한다.


```typescript
'use client'

export default function MyComponent() {
  // 에러: 서버에서 실행 시 window가 없음
  const width = window.innerWidth

  // useEffect는 클라이언트에서만 실행됨
  useEffect(() => {
    const width = window.innerWidth
  }, [])
}
```


### Client Component에서 Server Component를 import할 수 없다


Client Component는 다른 Client Component만 직접 import할 수 있다. Server Component를 사용하려면 `children`이나 props로 받아야 한다.


```typescript
// 불가능
'use client'
import ServerComponent from './server-component'

export default function ClientComponent() {
  return <ServerComponent />
}
```


```typescript
// children으로 받기
'use client'

export default function ClientComponent({ children }) {
  return <div>{children}</div>
}
```


### 직렬화 가능한 값만 전달할 수 있다


Server Component에서 Client Component로 props를 전달할 때는 직렬화 가능한 값만 보낼 수 있다. 함수, 클래스 인스턴스, Symbol 같은 값은 전달할 수 없다.


```typescript
// 불가능
<ClientComponent
  onClick={() => {}}  // 함수 전달 불가
  date={new Date()}   // Date 객체 전달 불가
/>

// 가능
<ClientComponent
  count={42}              // 숫자
  name="hello"            // 문자열
  data={{ id: 1 }}        // 객체
  items={[1, 2, 3]}       // 배열
  timestamp="2024-01-01"  // ISO 문자열
/>
```


이는 서버에서 컴포넌트를 렌더링한 결과를 JSON 형태로 클라이언트에 전송하기 때문이다. JSON으로 변환할 수 없는 값은 전달할 수 없다.


### 컴포넌트 계층 구조 설계


Client Component를 최대한 말단에 배치하는 것이 좋다. 상위에 Client Component가 있으면 그 하위의 모든 컴포넌트가 JavaScript 번들에 포함되어 용량이 커진다.


```typescript
// 비효율적인 구조
'use client'

export default function Page() {
  const [open, setOpen] = useState(false)

  return (
    <div>
      <Header />        {/* JavaScript 번들에 포함 */}
      <Content />       {/* JavaScript 번들에 포함 */}
      <Footer />        {/* JavaScript 번들에 포함 */}
      <Modal open={open} setOpen={setOpen} />
    </div>
  )
}
```


위 코드는 `Modal`의 상태 관리 때문에 전체를 Client Component로 만들었다. 이렇게 하면 `Header`, `Content`, `Footer` 같은 정적 컴포넌트까지 모두 JavaScript 번들에 포함되어 파일 크기가 커진다.


```typescript
// 효율적인 구조
export default function Page() {
  return (
    <div>
      <Header />        {/* Server Component */}
      <Content />       {/* Server Component */}
      <Footer />        {/* Server Component */}
      <ModalButton />   {/* Client Component */}
    </div>
  )
}
```


```typescript
// modal-button.tsx
'use client'

export default function ModalButton() {
  const [open, setOpen] = useState(false)

  return (
    <>
      <button onClick={() => setOpen(true)}>열기</button>
      <Modal open={open} setOpen={setOpen} />
    </>
  )
}
```


위 코드는 상태가 필요한 부분만 Client Component로 분리했다. `Header`, `Content`, `Footer`는 Server Component로 남아있어 JavaScript 번들에 포함되지 않는다. 이렇게 하면 번들 크기가 줄어들고 Time to Interactive(TTI)가 개선된다.


**핵심은 인터랙션이 필요한 최소한의 부분만 Client Component로 만드는 것이다.** 페이지 전체를 Client Component로 만들지 말고, 버튼이나 입력 폼처럼 실제로 상호작용이 필요한 부분만 분리한다.


## 참고 자료

- [Next.js 공식 문서 - Server Components](https://nextjs.org/docs/app/building-your-application/rendering/server-components)
- [Next.js 공식 문서 - Client Components](https://nextjs.org/docs/app/building-your-application/rendering/client-components)
- [Next.js 공식 문서 - Composition Patterns](https://nextjs.org/docs/app/building-your-application/rendering/composition-patterns)


React Server Component


## Link 컴포넌트로 페이지 이동하기


Next.js에서 페이지 간 이동은 `<Link>` 컴포넌트를 사용한다.


```typescript
import Link from 'next/link'

export default function Navigation() {
  return (
    <nav>
      <Link href="/">홈</Link>
      <Link href="/about">소개</Link>
      <Link href="/blog/post-1">블로그</Link>
    </nav>
  )
}
```


`<Link>`는 HTML의 `<a>` 태그를 확장한 것으로, 클라이언트 사이드 네비게이션을 제공한다. 페이지 전체를 새로고침하지 않고 필요한 부분만 교체해서 빠른 이동이 가능하다.


## RSC Payload와 JS Bundle


App Router에서는 Server Component와 Client Component가 분리되어 있어서, 페이지 이동 시 두 가지를 각각 불러온다.

- **RSC Payload**: Server Component의 렌더링 결과. 서버에서 생성된 HTML과 데이터를 담고 있다.
- **JS Bundle**: Client Component의 JavaScript 코드. 브라우저에서 실행될 인터랙티브한 부분이다.

Page Router에서는 JS Bundle만으로 모든 컴포넌트를 처리했지만, App Router에서는 서버와 클라이언트 컴포넌트가 분리되어 각각 필요한 것만 전송한다. 이를 통해 전송량을 줄이고 초기 로딩 속도를 개선한다.


## Prefetching


Prefetching은 사용자가 링크를 클릭하기 전에 미리 해당 페이지의 데이터를 불러오는 기능이다. `<Link>` 컴포넌트는 기본적으로 prefetching을 자동으로 수행한다.


### 작동 방식


링크가 뷰포트에 나타나면 Next.js는 백그라운드에서 해당 페이지를 미리 불러온다. 사용자가 실제로 클릭했을 때는 이미 데이터가 준비되어 있어서 즉시 페이지가 전환된다.


```typescript
// 기본: prefetching 활성화
<Link href="/dashboard">대시보드</Link>

// prefetching 비활성화
<Link href="/dashboard" prefetch={false}>대시보드</Link>
```


### Static vs Dynamic 라우트


Prefetching 동작은 라우트가 정적인지 동적인지에 따라 다르다.


**Static 라우트**는 빌드 타임에 미리 생성된 페이지다. 데이터가 고정되어 있고 모든 사용자에게 동일한 내용을 보여준다.


```typescript
// app/about/page.tsx - Static 라우트
export default function About() {
  return <div>소개 페이지</div>
}
```


Static 라우트는 **RSC Payload와 JS Bundle을 모두 prefetch** 한다. 페이지 전체를 미리 불러오기 때문에 이동이 즉각적이다.


**Dynamic 라우트**는 요청 시점에 렌더링되는 페이지다. 사용자마다 다른 데이터를 보여주거나 실시간 데이터를 표시한다.


```typescript
// app/dashboard/page.tsx - Dynamic 라우트
export default async function Dashboard() {
  const user = await getCurrentUser() // 요청 시점에 실행
  return <div>환영합니다, {user.name}님</div>
}
```


Dynamic 라우트는 **RSC Payload만 일부 prefetch** 한다. 전체 페이지를 미리 렌더링할 수 없기 때문에 레이아웃이나 로딩 상태만 미리 준비한다.


### 개발 모드 vs 프로덕션 모드


Prefetching은 프로덕션 모드에서만 활성화된다.

- **개발 모드** (`npm run dev`): Prefetching이 비활성화되어 있다. 링크를 클릭할 때만 RSC Payload와 JS Bundle을 불러온다.
- **프로덕션 모드** (`npm run build && npm start`): Prefetching이 활성화되어 링크가 뷰포트에 나타나면 자동으로 데이터를 미리 불러온다.

개발 중에는 prefetching이 작동하지 않으므로, 실제 성능을 확인하려면 빌드 후 프로덕션 모드로 실행해야 한다.


## 클라이언트 사이드 네비게이션


`<Link>` 컴포넌트를 사용하면 클라이언트 사이드 네비게이션이 가능하다. 페이지 전체가 새로고침되지 않고, 변경된 부분만 교체된다.


```typescript
export default function Page() {
  return (
    <div>
      <Header />  {/* 페이지 이동 시 유지됨 */}
      <Content /> {/* 이 부분만 교체됨 */}
      <Footer />  {/* 페이지 이동 시 유지됨 */}
    </div>
  )
}
```


Layout으로 감싸진 부분은 그대로 유지되고, 페이지 컴포넌트만 교체되므로 빠르고 부드러운 전환이 가능하다. 이는 SPA(Single Page Application)와 유사한 경험을 제공한다.


## 프로그래매틱 네비게이션


때로는 버튼 클릭이나 폼 제출 후에 프로그래밍으로 페이지를 이동해야 할 때가 있다. 이럴 때는 `useRouter` 훅을 사용한다.


```typescript
'use client'

import { useRouter } from 'next/navigation'

export default function LoginButton() {
  const router = useRouter()

  const handleLogin = async () => {
    await login()
    router.push('/dashboard')
  }

  return <button onClick={handleLogin}>로그인</button>
}
```


App Router에서는 `next/navigation`에서 `useRouter`를 import 한다. Page Router의 `next/router`와는 다른 API다.


주요 메서드는 다음과 같다.

- `router.push(href)`: 새로운 페이지로 이동
- `router.replace(href)`: 히스토리를 남기지 않고 이동
- `router.back()`: 이전 페이지로 이동
- `router.refresh()`: 현재 페이지 새로고침

## 참고 자료

- [Next.js 공식 문서 - Linking and Navigating](https://nextjs.org/docs/app/building-your-application/routing/linking-and-navigating)


App Router navigating


## Layout이란


Layout은 여러 페이지에서 공유되는 UI를 말한다. Next.js App Router에서 Layout은 다음과 같은 특징을 가진다.

- 페이지 전환 시 상태를 유지한다
- 재렌더링되지 않는다
- 인터랙션을 유지한다

## 기본 사용법


특정 폴더 안에 `layout.tsx` 파일을 만들면 해당 폴더와 하위 폴더의 모든 페이지가 이 Layout을 공유한다.


```typescript
export default function DashboardLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <section>
      <nav>네비게이션 바</nav>
      <main>{children}</main>
    </section>
  )
}
```


위 코드에서 `children` prop으로 해당 Layout 안에 렌더링될 페이지나 하위 Layout을 받는다. Layout 컴포넌트는 반드시 `children`을 받아서 렌더링해야 한다.


## Root Layout


`app` 디렉토리의 최상위에는 반드시 Root Layout이 있어야 한다. 이 Layout은 애플리케이션 전체에 적용되며, 다른 Layout과 달리 특별한 요구사항이 있다.


```typescript
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="ko">
      <body>{children}</body>
    </html>
  )
}
```


Root Layout은 `<html>`과 `<body>` 태그를 반드시 포함해야 한다. 이는 서버 사이드 렌더링 시 완전한 HTML 문서를 생성하기 위함이다.


## Layout 중첩


폴더 구조에 따라 Layout은 자동으로 중첩된다.


```plain text
app/
├── layout.tsx          # Root Layout
└── dashboard/
    ├── layout.tsx      # Dashboard Layout
    └── settings/
        ├── layout.tsx  # Settings Layout
        └── page.tsx    # Settings Page
```


위와 같은 구조에서 `/dashboard/settings` 경로에 접근하면 다음 순서로 중첩된다.

1. Root Layout이 Dashboard Layout을 감싼다
2. Dashboard Layout이 Settings Layout을 감싼다
3. Settings Layout이 Settings Page를 감싼다

각 Layout은 자신의 `children`으로 다음 단계의 Layout 또는 Page를 받는다.


## Layout의 동작 방식


Layout은 페이지 전환 시 재렌더링되지 않는다. 예를 들어 `/dashboard/analytics`에서 `/dashboard/settings`로 이동할 때, 두 페이지가 같은 Dashboard Layout을 공유한다면 Dashboard Layout은 그대로 유지되고 내부의 페이지 컴포넌트만 교체된다.


이로 인해 다음과 같은 이점이 있다.

- Layout 내부의 상태가 유지된다
- 불필요한 재렌더링을 방지해 성능이 향상된다
- Layout 내부의 인터랙티브한 요소가 초기화되지 않는다

## Route Group으로 Layout 구성하기


Route Group은 폴더 이름을 괄호 `(folderName)`로 감싸서 만든다. 이렇게 만든 폴더는 URL 경로에 포함되지 않고, 단순히 라우트를 구조화하는 용도로만 사용된다.


### Route Group의 활용


Route Group을 사용하면 다음과 같은 작업을 할 수 있다.

- 팀, 기능, 관심사별로 라우트를 논리적으로 그룹화한다
- 동일한 라우트 세그먼트 레벨에서 여러 개의 Root Layout을 정의한다
- 특정 라우트에만 선택적으로 Layout을 적용한다

### 사용 예시


```plain text
app/
├── (marketing)/
│   ├── layout.tsx      # 마케팅 전용 Layout
│   ├── about/
│   │   └── page.tsx    # URL: /about
│   └── blog/
│       └── page.tsx    # URL: /blog
└── (shop)/
    ├── layout.tsx      # 쇼핑 전용 Layout
    ├── products/
    │   └── page.tsx    # URL: /products
    └── cart/
        └── page.tsx    # URL: /cart
```


위 구조에서 `(marketing)`과 `(shop)`은 URL에 포함되지 않는다. `/about` 페이지는 마케팅 Layout을 사용하고, `/products` 페이지는 쇼핑 Layout을 사용한다.


### 여러 Root Layout 만들기


Route Group을 사용하면 하나의 앱 안에서 완전히 다른 Root Layout을 여러 개 만들 수 있다.


```plain text
app/
├── (site)/
│   ├── layout.tsx      # 일반 사이트용 Root Layout
│   └── page.tsx        # URL: /
└── (admin)/
    ├── layout.tsx      # 관리자용 Root Layout
    └── page.tsx        # URL: /admin (route group 내부에서는 /page로 처리)
```


다만 서로 다른 Root Layout 사이를 이동할 때는 전체 페이지가 다시 로드된다. 같은 Root Layout 내에서 이동할 때처럼 부분 렌더링이 일어나지 않는다.


### 주의사항


공식 문서에서 언급하는 주의사항이다.

- 서로 다른 Route Group에서 같은 URL 경로가 생기지 않도록 해야 한다. 예를 들어 `(shop)/products/page.tsx`와 `(marketing)/products/page.tsx`는 둘 다 `/products` URL을 만들기 때문에 충돌이 발생한다.
- 여러 Root Layout을 사용할 때, 홈 페이지 `/`는 반드시 하나의 Route Group 안에 정의되어야 한다.

## 참고 자료

- [Next.js 공식 문서 - Layouts and Templates](https://nextjs.org/docs/app/building-your-application/routing/layouts-and-templates)
- [Next.js 공식 문서 - Route Groups](https://nextjs.org/docs/app/building-your-application/routing/route-groups)


App Router Layout 설정하기


## Page Router의 데이터 페칭 방식과 한계


Page Router에서는 서버 컴포넌트라는 개념이 없었다. 모든 컴포넌트가 클라이언트 컴포넌트로서 서버와 클라이언트 양쪽에서 실행되었기 때문에, 서버에서만 데이터를 가져오려면 `getServerSideProps`나 `getStaticProps` 같은 특수한 함수를 사용해야 했다.


```javascript
// Page Router 방식
export default function Page({ data }) {
  return <div>{data.title}</div>;
}

export async function getServerSideProps() {
  const res = await fetch('<https://api.example.com/data>');
  const data = await res.json();

  return {
    props: { data }
  };
}
```


이 방식의 문제는 **데이터 흐름의 비효율성**이다. 서버에서 가져온 데이터는 항상 페이지 최상단에 위치하게 되고, 실제로 그 데이터가 필요한 하위 컴포넌트까지 props나 Context API로 전달해야 한다. 컴포넌트 트리가 깊어질수록 props drilling이 심해지고, 데이터가 필요한 곳에서 직접 가져올 수 없다는 근본적인 제약이 있었다.


## App Router의 해결 방법


App Router에서는 서버 컴포넌트가 추가되면서 이런 문제가 해결되었다. 서버 컴포넌트는 서버에서만 실행되기 때문에 컴포넌트 함수 자체를 `async`로 선언하고 내부에서 직접 데이터를 가져올 수 있다.


```javascript
// App Router 방식
async function PostList() {
  const res = await fetch('<https://api.example.com/posts>');
  const posts = await res.json();

  return (
    <ul>
      {posts.map(post => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}
```


위 코드에서 `PostList` 컴포넌트는 서버 컴포넌트다. 서버에서만 실행되므로 브라우저 환경에서 발생할 수 있는 비동기 처리 문제를 신경 쓸 필요가 없다. 기존에는 클라이언트 컴포넌트에서 `async` 키워드를 사용하면 브라우저에서 동작할 때 문제를 일으킬 수 있어 권장되지 않았지만, 서버 컴포넌트는 브라우저에 전송되지 않으므로 안전하게 사용할 수 있다.


## 주요 변화점


이제 `getServerSideProps`, `getStaticProps` 같은 함수를 사용하지 않아도 된다. **데이터가 필요한 컴포넌트에서 직접 가져오면** 된다. Next.js 공식 문서에서 강조하는 "fetching data where it's needed"라는 best practice가 이제 실제로 가능해진 것이다.


```javascript
// 페이지 컴포넌트
export default function BlogPage() {
  return (
    <div>
      <Header />
      <PostList />  {/* 데이터가 필요한 곳에서 직접 fetch */}
      <Sidebar />
    </div>
  );
}

// 데이터가 필요한 컴포넌트
async function PostList() {
  const posts = await fetchPosts();
  return <ul>...</ul>;
}
```


데이터를 상위에서 하위로 전달할 필요가 없어지면서 컴포넌트 구조가 단순해지고, 각 컴포넌트가 자신이 필요한 데이터를 독립적으로 관리할 수 있게 되었다.


## 서버 컴포넌트에서 데이터 페칭 패턴


서버 컴포넌트에서 데이터를 가져오는 기본 패턴은 다음과 같다.


```javascript
async function ProductDetail({ id }) {
  // 1. fetch 요청
  const res = await fetch(`https://api.example.com/products/${id}`);

  // 2. 에러 처리
  if (!res.ok) {
    throw new Error('Failed to fetch product');
  }

  // 3. 데이터 파싱
  const product = await res.json();

  // 4. 렌더링
  return (
    <div>
      <h1>{product.name}</h1>
      <p>{product.description}</p>
      <p>Price: ${product.price}</p>
    </div>
  );
}
```


컴포넌트 함수를 `async`로 선언하고, 내부에서 `await`로 비동기 작업을 처리한다. 이 컴포넌트는 서버에서 데이터를 가져온 후 완성된 HTML을 클라이언트에 전송하므로, 사용자는 로딩 상태 없이 바로 완성된 콘텐츠를 볼 수 있다.


## fetch API 확장 기능


App Router의 서버 컴포넌트에서 사용하는 `fetch`는 Web API의 표준 fetch를 확장한 것으로, Next.js만의 추가 기능을 제공한다.


```javascript
// 캐싱 제어
const res = await fetch('<https://api.example.com/data>', {
  cache: 'force-cache'  // 기본값: 캐시 사용
});

const res2 = await fetch('<https://api.example.com/data>', {
  cache: 'no-store'  // 매번 새로 가져오기
});

// 재검증 시간 설정
const res3 = await fetch('<https://api.example.com/data>', {
  next: { revalidate: 60 }  // 60초마다 재검증
});
```


이 옵션들을 통해 SSG, SSR, ISR 방식을 자연스럽게 구현할 수 있다.


## 병렬 데이터 페칭


여러 데이터를 동시에 가져와야 할 때는 `Promise.all`을 사용하면 된다.


```javascript
async function Dashboard() {
  const [user, posts, comments] = await Promise.all([
    fetch('/api/user').then(r => r.json()),
    fetch('/api/posts').then(r => r.json()),
    fetch('/api/comments').then(r => r.json())
  ]);

  return (
    <div>
      <UserProfile user={user} />
      <PostList posts={posts} />
      <CommentList comments={comments} />
    </div>
  );
}
```


세 개의 API 요청이 순차적이 아닌 병렬로 실행되어 전체 로딩 시간이 단축된다.


## 클라이언트 컴포넌트에서의 데이터 페칭


클라이언트 컴포넌트에서는 여전히 `useEffect`나 React Query 같은 라이브러리를 사용해 데이터를 가져온다.


```javascript
'use client'

import { useState, useEffect } from 'react';

export default function ClientComponent() {
  const [data, setData] = useState(null);

  useEffect(() => {
    fetch('/api/data')
      .then(r => r.json())
      .then(setData);
  }, []);

  if (!data) return <div>Loading...</div>;

  return <div>{data.title}</div>;
}
```


서버 컴포넌트에서는 `async/await`로 간단하게 처리하고, 클라이언트 컴포넌트에서는 기존 방식을 사용하는 것이 일반적인 패턴이다.



App Router data fetching


## 사전 렌더링이란


Next.js는 모든 페이지를 기본적으로 사전 렌더링(Pre-rendering)한다. 클라이언트 측 JavaScript가 모든 작업을 처리하는 전통적인 React SPA와 달리, Next.js는 서버에서 미리 HTML을 생성한다.


사전 렌더링의 핵심 장점은 초기 로딩 성능과 SEO 개선이다. 서버에서 완성된 HTML을 보내기 때문에 브라우저는 즉시 컨텐츠를 표시할 수 있고, 검색 엔진 크롤러도 페이지 내용을 정확히 파악할 수 있다.


Next.js는 세 가지 사전 렌더링 방식을 제공한다. 각 방식은 페이지를 생성하는 시점과 주기가 다르며, 데이터의 신선도와 성능 사이에서 서로 다른 균형점을 찾는다.


## SSR (Server-Side Rendering)


### 왜 필요한가


서버 사이드 렌더링은 요청이 들어올 때마다 서버에서 HTML을 새로 생성한다. 사용자마다 다른 컨텐츠를 보여주거나, 실시간으로 변하는 데이터를 표시해야 할 때 필요하다.


예를 들어 대시보드 페이지는 로그인한 사용자의 최신 활동 내역을 보여줘야 한다. 이런 경우 빌드 타임에 미리 만들어둔 정적 페이지로는 해결할 수 없다.


### 동작 방식


SSR은 `getServerSideProps` 함수로 구현한다. 이 함수는 매 요청마다 서버에서 실행되며, 데이터를 가져온 뒤 페이지 컴포넌트에 props로 전달한다.


```typescript
export default function Dashboard({ userData }) {
  return (
    <div>
      <h1>{userData.name}의 대시보드</h1>
      <p>마지막 로그인: {userData.lastLogin}</p>
    </div>
  )
}

export async function getServerSideProps(context) {
  const { req, res } = context

  // 쿠키에서 사용자 정보 가져오기
  const userId = req.cookies.userId

  // API에서 최신 데이터 조회
  const response = await fetch(`https://api.example.com/users/${userId}`)
  const userData = await response.json()

  return {
    props: {
      userData
    }
  }
}
```


위 코드에서 사용자가 `/dashboard` 페이지를 요청하면 Next.js는 먼저 `getServerSideProps`를 실행한다. 이 함수는 쿠키에서 사용자 ID를 읽고, API를 호출해서 최신 데이터를 가져온다. 그 다음 이 데이터를 props로 전달받은 컴포넌트가 렌더링되어 HTML로 변환되고, 최종적으로 브라우저에 전송된다.


### 타입 추론


TypeScript를 사용할 때는 `InferGetServerSidePropsType`으로 props 타입을 자동 추론할 수 있다.


```typescript
import type { InferGetServerSidePropsType } from 'next'

export default function Dashboard({
  userData
}: InferGetServerSidePropsType<typeof getServerSideProps>) {
  // userData의 타입이 자동으로 추론됨
}
```


### 실행 환경


`getServerSideProps`는 오직 서버에서만 실행된다. 이 함수 안에서 `console.log`를 찍으면 브라우저 콘솔이 아닌 Next.js 서버 터미널에 출력된다. 따라서 데이터베이스 직접 조회나 서버 파일 시스템 접근 같은 서버 전용 작업을 안전하게 수행할 수 있다.


### 장단점


SSR의 장점은 항상 최신 데이터를 보여줄 수 있다는 점이다. 매 요청마다 새로 렌더링하기 때문에 실시간성이 중요한 페이지에 적합하다.


하지만 단점도 명확하다. 데이터를 가져오는 API가 느리면 사용자는 빈 화면을 오래 봐야 한다. 서버는 매번 렌더링 작업을 수행해야 하므로 트래픽이 많을수록 서버 부하가 증가한다. CDN 캐싱도 기본적으로는 불가능하다.


## SSG (Static Site Generation)


### 왜 필요한가


정적 사이트 생성은 빌드 타임에 페이지를 미리 만들어둔다. SSR의 성능 문제를 해결하기 위해 등장했다. 내용이 자주 바뀌지 않는 페이지라면 매번 서버에서 렌더링할 필요가 없다.


블로그 글, 문서 페이지, 상품 목록처럼 모든 사용자에게 동일한 컨텐츠를 보여주는 경우 SSG가 가장 효율적이다.


### 동작 방식


SSG는 `getStaticProps` 함수로 구현한다. 이 함수는 빌드할 때 한 번만 실행되며, 가져온 데이터로 HTML 파일을 생성한다.


```typescript
export default function BlogPost({ post }) {
  return (
    <article>
      <h1>{post.title}</h1>
      <div>{post.content}</div>
    </article>
  )
}

export async function getStaticProps() {
  const response = await fetch('<https://api.example.com/posts/1>')
  const post = await response.json()

  return {
    props: {
      post
    }
  }
}
```


위 코드는 빌드 시점에 실행되어 HTML 파일을 생성한다. 사용자가 페이지를 요청하면 서버는 이미 만들어진 HTML을 즉시 반환한다. API 호출이나 렌더링 과정이 필요 없으므로 응답 속도가 빠르다.


### 동적 라우팅


동적 라우팅(예: `/posts/[id]`)을 사용하는 경우 `getStaticPaths`로 어떤 경로들을 미리 생성할지 지정해야 한다.


```typescript
// pages/posts/[id].tsx

export async function getStaticPaths() {
  const response = await fetch('<https://api.example.com/posts>')
  const posts = await response.json()

  const paths = posts.map(post => ({
    params: { id: post.id.toString() }
  }))

  return {
    paths,
    fallback: false
  }
}

export async function getStaticProps({ params }) {
  const response = await fetch(`https://api.example.com/posts/${params.id}`)
  const post = await response.json()

  return {
    props: {
      post
    }
  }
}
```


`getStaticPaths`는 빌드 시점에 어떤 ID들로 페이지를 만들지 결정한다. 위 예시에서는 API에서 모든 포스트 목록을 가져와서, 각 포스트마다 정적 페이지를 생성한다. 예를 들어 포스트가 10개라면 `/posts/1`, `/posts/2`, ... `/posts/10` 경로의 HTML이 모두 빌드 시점에 만들어진다.


### fallback 옵션


`fallback` 옵션은 `getStaticPaths`에서 지정하지 않은 경로로 요청이 들어왔을 때 어떻게 처리할지 결정한다.


```typescript
return {
  paths,
  fallback: false  // 404 반환
  // fallback: true  // 빌드 후 생성
  // fallback: 'blocking'  // SSR처럼 동작
}
```


`fallback: false`는 지정한 경로 외에는 모두 404를 반환한다. `fallback: true`는 존재하지 않는 경로를 요청하면 즉시 빈 페이지를 보여주고 백그라운드에서 페이지를 생성한 뒤 교체한다. `fallback: 'blocking'`은 SSR처럼 동작해서 페이지 생성이 완료될 때까지 기다린 후 완성된 HTML을 반환한다.


대규모 사이트에서 모든 페이지를 빌드 시점에 생성하면 시간이 오래 걸린다. 이럴 때는 자주 접근하는 페이지만 미리 생성하고, 나머지는 `fallback: 'blocking'`으로 처리하는 것이 효율적이다.


### 제약사항


SSG는 요청 시점의 정보에 접근할 수 없다. 예를 들어 검색 페이지에서 쿼리 파라미터로 검색어를 받는다면, 빌드 시점에는 사용자가 어떤 검색어를 입력할지 알 수 없으므로 SSG를 사용할 수 없다.


```typescript
// pages/search.tsx
export async function getStaticProps(context) {
  // context.query는 빌드 시점에 undefined
  const searchTerm = context.query.q  // 이 값을 알 수 없음

  return {
    props: {}
  }
}
```


이런 경우에는 클라이언트에서 직접 데이터를 가져오거나 SSR을 사용해야 한다.


### 장단점


SSG의 장점은 속도다. 이미 만들어진 HTML을 반환하기만 하면 되므로 응답이 즉각적이다. CDN에 캐싱할 수 있어서 전 세계 어디서든 빠른 접근이 가능하다. 서버 부하도 거의 없다.


단점은 데이터 신선도다. 빌드 이후로는 페이지가 업데이트되지 않기 때문에 컨텐츠가 변경되어도 재배포하기 전까지는 이전 내용이 표시된다.


## ISR (Incremental Static Regeneration)


### 왜 필요한가


증분 정적 재생성은 SSG의 성능 장점을 유지하면서 데이터 신선도 문제를 해결한다. 모든 요청마다 렌더링하지는 않지만, 일정 주기로 페이지를 재생성해서 최신 상태를 유지한다.


블로그 조회수처럼 실시간성이 중요하지는 않지만 완전히 정적이지도 않은 데이터를 다룰 때 유용하다.


### 시간 기반 ISR


`getStaticProps`에서 `revalidate` 옵션을 추가하면 ISR이 활성화된다.


```typescript
export async function getStaticProps() {
  const response = await fetch('<https://api.example.com/posts>')
  const posts = await response.json()

  return {
    props: {
      posts
    },
    revalidate: 60  // 60초
  }
}
```


위 코드는 60초마다 페이지를 재검증한다. 동작 방식은 다음과 같다.


첫 번째 요청이 들어오면 캐시된 페이지를 즉시 반환한다. 만약 마지막 생성 시점으로부터 60초가 지났다면, Next.js는 백그라운드에서 페이지를 재생성한다. 재생성이 완료되면 새로운 버전으로 교체되고, 그 다음 요청부터는 업데이트된 페이지가 제공된다.


중요한 점은 재생성 중에도 이전 버전의 페이지가 계속 제공된다는 것이다. 사용자는 절대 로딩 화면을 보지 않는다. 이를 Stale-While-Revalidate 전략이라고 한다.


### On-Demand ISR


시간 기반 ISR은 주기적으로 재생성하지만, 때로는 특정 시점에 즉시 업데이트해야 할 때가 있다. 예를 들어 관리자가 블로그 글을 수정했다면, 다음 `revalidate` 주기를 기다리지 않고 바로 페이지를 갱신하고 싶다.


On-Demand ISR은 API 라우트에서 `res.revalidate()` 메서드로 특정 경로를 즉시 재생성할 수 있다.


```typescript
// pages/api/revalidate.ts

export default async function handler(req, res) {
  // 비밀 토큰으로 인증
  if (req.query.secret !== process.env.REVALIDATE_TOKEN) {
    return res.status(401).json({ message: 'Invalid token' })
  }

  try {
    // 특정 경로 재검증
    await res.revalidate('/posts/1')
    return res.json({ revalidated: true })
  } catch (err) {
    return res.status(500).send('Error revalidating')
  }
}
```


위 코드는 `/api/revalidate?secret=TOKEN` 엔드포인트를 호출하면 `/posts/1` 페이지를 즉시 재생성한다. CMS 웹훅과 연결하면 컨텐츠 수정 시 자동으로 페이지를 갱신할 수 있다.


```typescript
// CMS에서 글 수정 후 웹훅으로 호출
await fetch(`https://yoursite.com/api/revalidate?secret=${token}&path=/posts/${postId}`)
```


### 주의사항


ISR은 Node.js 런타임에서만 동작한다. `next export`로 생성한 정적 사이트에서는 사용할 수 없다.


On-Demand ISR로 재검증을 트리거할 때 미들웨어는 실행되지 않는다. 인증이나 로깅이 필요하다면 API 라우트 내부에서 직접 처리해야 한다.


`revalidate` 값이 너무 짧으면 서버 부하가 증가하고, 너무 길면 데이터가 오래된 채로 유지된다. 컨텐츠 업데이트 빈도와 트래픽 패턴을 고려해서 적절한 값을 설정해야 한다.


## 페이지 별 특성에 맞는 렌더링 방식 선택


각 페이지의 특성에 맞는 렌더링 방식을 선택해야 한다.


SSR을 사용해야 하는 경우는 사용자별로 다른 컨텐츠를 보여주는 대시보드나 마이페이지, 실시간 데이터를 표시하는 주식 시세나 스포츠 스코어, 요청 헤더나 쿠키를 읽어야 하는 인증 페이지에 적합하다.


SSG를 사용해야 하는 경우는 마케팅 랜딩 페이지, 블로그 글, 제품 소개 페이지, 도움말 문서처럼 모든 사용자에게 동일한 컨텐츠를 보여주고 데이터가 거의 바뀌지 않는 페이지다.


ISR을 사용해야 하는 경우는 블로그 조회수나 좋아요 수처럼 자주 변하지만 실시간성이 중요하지 않은 데이터, 뉴스 기사처럼 주기적으로 업데이트되는 컨텐츠, 전자상거래 상품 목록처럼 재고나 가격이 변경되는 페이지다.


하나의 애플리케이션에서 여러 방식을 혼합해서 사용하는 것이 일반적이다. Next.js는 페이지별로 다른 렌더링 방식을 적용할 수 있으므로, 각 페이지의 요구사항에 맞는 최적의 전략을 선택하면 된다.


## 참고 자료

- [Next.js 공식 문서 - Server-side Rendering](https://nextjs.org/docs/pages/building-your-application/rendering/server-side-rendering)
- [Next.js 공식 문서 - Static Site Generation](https://nextjs.org/docs/pages/building-your-application/rendering/static-site-generation)
- [Next.js 공식 문서 - Incremental Static Regeneration](https://nextjs.org/docs/pages/building-your-application/rendering/incremental-static-regeneration)


사전 렌더링 방식 - SSR, SSG, ISR


Next.js에서 페이지마다 다른 레이아웃을 적용하는 패턴이다. `_app.tsx`에서 모든 페이지에 동일한 레이아웃을 적용하는 대신, 각 페이지가 자신만의 레이아웃을 정의할 수 있다.


## 왜 필요한가?


일반적으로 `_app.tsx`에서 레이아웃을 적용하면 모든 페이지가 동일한 레이아웃을 사용한다.


```typescript
// pages/_app.tsx
export default function App({ Component, pageProps }: AppProps) {
  return (
    <Layout>
      <Component {...pageProps} />
    </Layout>
  );
}
```


하지만 실제 애플리케이션에서는 페이지마다 다른 레이아웃이 필요한 경우가 많다.

- 홈페이지는 헤더만 있고 사이드바가 없다
- 대시보드는 사이드바가 있다
- 관리자 페이지는 다른 네비게이션을 사용한다
- 로그인 페이지는 레이아웃이 아예 없다

Per-page Layouts 패턴을 사용하면 각 페이지가 필요한 레이아웃을 자유롭게 선택할 수 있다.


## 기본 구조


페이지 컴포넌트에 `getLayout` 메서드를 추가하고, `_app.tsx`에서 이를 호출하는 방식이다.


### 1. `_app.tsx` 설정


```typescript
// pages/_app.tsx
import type { AppProps } from 'next/app';
import type { ReactElement, ReactNode } from 'react';
import type { NextPage } from 'next';

type NextPageWithLayout = NextPage & {
  getLayout?: (page: ReactElement) => ReactNode;
};

type AppPropsWithLayout = AppProps & {
  Component: NextPageWithLayout;
};

export default function App({ Component, pageProps }: AppPropsWithLayout) {
  // getLayout이 있으면 사용, 없으면 페이지 그대로 렌더링
  const getLayout = Component.getLayout ?? ((page) => page);

  return getLayout(<Component {...pageProps} />);
}
```


위 코드에서 `Component.getLayout`이 있는지 확인한다. 있으면 해당 함수를 호출하여 페이지를 레이아웃으로 감싸고, 없으면 페이지를 그대로 렌더링한다.


`??` 연산자는 왼쪽 값이 `null` 또는 `undefined`일 때 오른쪽 값을 사용한다.


### 2. 레이아웃이 필요한 페이지


```typescript
// pages/dashboard.tsx
import { ReactElement } from 'react';
import DashboardLayout from '@/components/DashboardLayout';

export default function Dashboard() {
  return (
    <div>
      <h1>대시보드</h1>
      <p>통계와 차트가 여기에 표시된다</p>
    </div>
  );
}

Dashboard.getLayout = function getLayout(page: ReactElement) {
  return <DashboardLayout>{page}</DashboardLayout>;
};
```


페이지 컴포넌트에 `getLayout` 메서드를 추가한다. 이 메서드는 페이지를 받아서 레이아웃으로 감싼 결과를 반환한다.


### 3. 레이아웃이 없는 페이지


```typescript
// pages/login.tsx
export default function Login() {
  return (
    <div>
      <h1>로그인</h1>
      <form>{/* 로그인 폼 */}</form>
    </div>
  );
}

// getLayout을 정의하지 않으면 레이아웃 없이 페이지만 렌더링된다
```


`getLayout`을 정의하지 않으면 `_app.tsx`에서 `(page) => page`가 사용되어 페이지가 그대로 렌더링된다.


## 레이아웃 컴포넌트 작성


레이아웃 컴포넌트는 일반적인 React 컴포넌트다.


```typescript
// components/DashboardLayout.tsx
import Link from 'next/link';
import { ReactNode } from 'react';

export default function DashboardLayout({ children }: { children: ReactNode }) {
  return (
    <div>
      <nav>
        <Link href="/dashboard">대시보드</Link>
        <Link href="/dashboard/analytics">분석</Link>
        <Link href="/dashboard/settings">설정</Link>
      </nav>
      <main>{children}</main>
    </div>
  );
}
```


`children` prop으로 페이지 컴포넌트를 받아서 원하는 위치에 렌더링한다.


## 중첩 레이아웃


레이아웃 안에 또 다른 레이아웃을 중첩할 수 있다.


```typescript
// pages/dashboard/analytics.tsx
import { ReactElement } from 'react';
import DashboardLayout from '@/components/DashboardLayout';
import AnalyticsLayout from '@/components/AnalyticsLayout';

export default function Analytics() {
  return <div>분석 페이지 내용</div>;
}

Analytics.getLayout = function getLayout(page: ReactElement) {
  return (
    <DashboardLayout>
      <AnalyticsLayout>{page}</AnalyticsLayout>
    </DashboardLayout>
  );
};
```


위 코드는 `DashboardLayout` 안에 `AnalyticsLayout`을 중첩한다. 페이지 전환 시 `DashboardLayout`의 상태는 유지되고 `AnalyticsLayout`만 교체된다.


## 레이아웃 상태 유지


Per-page Layouts의 중요한 장점은 페이지 전환 시 레이아웃의 상태가 유지된다는 점이다.


```typescript
// components/DashboardLayout.tsx
import { useState } from 'react';
import Link from 'next/link';

export default function DashboardLayout({ children }: { children: ReactNode }) {
  const [sidebarOpen, setSidebarOpen] = useState(true);

  return (
    <div>
      <button onClick={() => setSidebarOpen(!sidebarOpen)}>
        사이드바 토글
      </button>

      {sidebarOpen && (
        <nav>
          <Link href="/dashboard">대시보드</Link>
          <Link href="/dashboard/analytics">분석</Link>
        </nav>
      )}

      <main>{children}</main>
    </div>
  );
}
```


사용자가 사이드바를 닫은 상태에서 `/dashboard`에서 `/dashboard/analytics`로 이동해도 사이드바는 닫힌 상태로 유지된다. 같은 레이아웃을 사용하는 페이지 간 이동에서는 레이아웃이 언마운트되지 않기 때문이다.


## TypeScript 타입 정의


타입 안정성을 위해 페이지 타입을 확장할 수 있다.


```typescript
// types/page.ts
import type { NextPage } from 'next';
import type { ReactElement, ReactNode } from 'react';

export type NextPageWithLayout<P = {}, IP = P> = NextPage<P, IP> & {
  getLayout?: (page: ReactElement) => ReactNode;
};
```


```typescript
// pages/_app.tsx
import type { AppProps } from 'next/app';
import type { NextPageWithLayout } from '@/types/page';

type AppPropsWithLayout = AppProps & {
  Component: NextPageWithLayout;
};

export default function App({ Component, pageProps }: AppPropsWithLayout) {
  const getLayout = Component.getLayout ?? ((page) => page);
  return getLayout(<Component {...pageProps} />);
}
```


```typescript
// pages/dashboard.tsx
import type { NextPageWithLayout } from '@/types/page';
import DashboardLayout from '@/components/DashboardLayout';

const Dashboard: NextPageWithLayout = () => {
  return <div>대시보드</div>;
};

Dashboard.getLayout = function getLayout(page) {
  return <DashboardLayout>{page}</DashboardLayout>;
};

export default Dashboard;
```


타입을 정의하면 `getLayout` 메서드의 시그니처가 자동완성되고 타입 체크가 된다.


## 주의사항


### getLayout은 Next.js 기능이 아니다


`getLayout`은 Next.js가 제공하는 API가 아니라 **개발자가 만드는 패턴**이다. JavaScript에서 함수도 객체이므로 함수 컴포넌트에 프로퍼티를 추가할 수 있다.


이름도 `getLayout` 대신 `withLayout`, `customLayout` 등 원하는 대로 정할 수 있다. 다만 Next.js 공식 문서에서 `getLayout`이라는 이름으로 소개했기 때문에 이것이 관례가 되었다.


### _app.tsx 레이아웃과 함께 사용


Per-page Layouts와 `_app.tsx`의 레이아웃을 함께 사용할 수도 있다.


```typescript
// pages/_app.tsx
export default function App({ Component, pageProps }: AppPropsWithLayout) {
  const getLayout = Component.getLayout ?? ((page) => page);

  return (
    <GlobalLayout>
      {getLayout(<Component {...pageProps} />)}
    </GlobalLayout>
  );
}
```


위 코드는 모든 페이지에 `GlobalLayout`을 적용하고, 추가로 각 페이지의 `getLayout`도 적용한다.


### getStaticProps, getServerSideProps와 함께 사용


Per-page Layouts는 데이터 페칭 메서드와 함께 사용할 수 있다.


```typescript
// pages/posts/[id].tsx
import type { NextPageWithLayout } from '@/types/page';
import { GetStaticProps, GetStaticPaths } from 'next';
import BlogLayout from '@/components/BlogLayout';

type Props = {
  post: {
    id: string;
    title: string;
    content: string;
  };
};

const Post: NextPageWithLayout<Props> = ({ post }) => {
  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </article>
  );
};

Post.getLayout = function getLayout(page) {
  return <BlogLayout>{page}</BlogLayout>;
};

export const getStaticProps: GetStaticProps<Props> = async ({ params }) => {
  // 데이터 페칭 로직
  const post = await fetchPost(params?.id as string);
  return { props: { post } };
};

export const getStaticPaths: GetStaticPaths = async () => {
  // 경로 생성 로직
  return { paths: [], fallback: 'blocking' };
};

export default Post;
```


데이터 페칭과 레이아웃 설정을 모두 같은 페이지 파일에서 처리할 수 있다.


## 참고 자료

- [Next.js 공식 문서 - Pages and Layouts](https://nextjs.org/docs/pages/building-your-application/routing/pages-and-layouts)


Per-page Layouts


Next.js의 Page Router는 `pages` 폴더 내의 파일 구조를 기반으로 자동으로 라우팅을 생성하는 시스템이다. 별도의 라우팅 설정 파일 없이 파일과 폴더만으로 URL 경로를 정의할 수 있다.

> Page Router vs App Router  
> Next.js 13부터 App Router가 도입되었지만, Page Router는 여전히 안정적이고 널리 사용된다. App Router는 Server Components를 기본으로 하는 새로운 패러다임이며, Page Router는 기존의 Client-side Navigation을 중심으로 한다.

## 기본 라우팅


`pages` 폴더 내의 파일이 자동으로 라우트가 된다. 파일명이 곧 URL 경로다.


```plain text
pages/
├── index.tsx          → /
├── about.tsx          → /about
├── contact.tsx        → /contact
└── products.tsx       → /products
```


위 구조에서 `index.tsx`는 루트 경로 `/`에 매핑되고, `about.tsx`는 `/about` 경로에 매핑된다.


```typescript
// pages/index.tsx
export default function Home() {
  return <h1>홈 페이지</h1>;
}
```


```typescript
// pages/about.tsx
export default function About() {
  return <h1>소개 페이지</h1>;
}
```


각 파일은 기본적으로 React 컴포넌트를 default export 해야 한다. Next.js는 이 컴포넌트를 자동으로 페이지로 렌더링한다.


## 중첩 라우팅


폴더를 사용하면 중첩된 경로를 만들 수 있다.


```plain text
pages/
├── index.tsx              → /
├── blog/
│   ├── index.tsx          → /blog
│   ├── first-post.tsx     → /blog/first-post
│   └── second-post.tsx    → /blog/second-post
└── products/
    ├── index.tsx          → /products
    └── electronics.tsx    → /products/electronics
```


폴더 내의 `index.tsx`는 해당 폴더 경로의 기본 페이지가 된다. 예를 들어 `blog/index.tsx`는 `/blog` 경로에 매핑된다.


```typescript
// pages/blog/index.tsx
export default function Blog() {
  return <h1>블로그 목록</h1>;
}
```


```typescript
// pages/blog/first-post.tsx
export default function FirstPost() {
  return <h1>첫 번째 포스트</h1>;
}
```


이렇게 폴더 구조만으로 직관적인 URL 계층을 구성할 수 있다.


## 동적 라우팅 (URL Parameter)


동적 경로를 갖는 페이지를 생성하려면 파일명을 대괄호로 감싸면 된다. `[id].tsx`와 같이 작성하면 해당 부분이 동적 세그먼트가 된다.


```plain text
pages/
└── posts/
    ├── index.tsx          → /posts
    └── [id].tsx           → /posts/:id
```


`[id].tsx` 파일은 `/posts/1`, `/posts/abc`, `/posts/hello` 등 모든 경로에 매칭된다.


```typescript
// pages/posts/[id].tsx
import { useRouter } from 'next/router';

export default function Post() {
  const router = useRouter();
  const { id } = router.query;

  return <h1>포스트 ID: {id}</h1>;
}
```


위 코드에서 `useRouter` 훅을 통해 URL의 동적 파라미터에 접근할 수 있다. `router.query` 객체에서 파일명에 정의한 `id`를 구조 분해 할당으로 가져온다.


사용자가 `/posts/123`에 접속하면 `id`는 `"123"`이 되고, `/posts/hello`에 접속하면 `id`는 `"hello"`가 된다.


### 여러 동적 세그먼트


여러 동적 세그먼트를 조합할 수도 있다.


```plain text
pages/
└── posts/
    └── [category]/
        └── [id].tsx       → /posts/:category/:id
```


```typescript
// pages/posts/[category]/[id].tsx
import { useRouter } from 'next/router';

export default function Post() {
  const router = useRouter();
  const { category, id } = router.query;

  return (
    <div>
      <h1>카테고리: {category}</h1>
      <p>포스트 ID: {id}</p>
    </div>
  );
}
```


`/posts/tech/123`에 접속하면 `category`는 `"tech"`, `id`는 `"123"`이 된다.


## Query String


Query String은 페이지 경로에 영향을 주지 않으며, `?` 뒤에 오는 파라미터들을 의미한다. 예를 들어 `/search?q=nextjs&sort=latest`에서 `q`와 `sort`가 Query String이다.


별도의 설정 없이 `useRouter` 훅의 `query` 속성으로 접근할 수 있다.

> 주의: next/router 사용useRouter는 next/router에서 import 해야 한다. next/navigation의 useRouter는 App Router 전용이므로 Page Router에서는 사용할 수 없다.

```typescript
// pages/search.tsx
import { useRouter } from 'next/router';

export default function Search() {
  const router = useRouter();
  const { q, sort } = router.query;

  return (
    <div>
      <h1>검색어: {q}</h1>
      <p>정렬: {sort}</p>
    </div>
  );
}
```


사용자가 `/search?q=nextjs&sort=latest`에 접속하면 `q`는 `"nextjs"`, `sort`는 `"latest"`가 된다.


Query String은 동적 라우팅 파라미터와 함께 사용할 수도 있다. 모든 파라미터는 `router.query`에 통합된다.


```typescript
// pages/posts/[id].tsx
import { useRouter } from 'next/router';

export default function Post() {
  const router = useRouter();
  const { id, comments } = router.query;

  return (
    <div>
      <h1>포스트 ID: {id}</h1>
      {comments && <p>댓글 표시 모드</p>}
    </div>
  );
}
```


`/posts/123?comments=true`에 접속하면 `id`는 `"123"`, `comments`는 `"true"`가 된다.


## Catch-all Routes


단일 동적 세그먼트는 한 단계의 경로만 매칭한다. `/posts/[id].tsx`는 `/posts/123`은 매칭하지만 `/posts/123/comments`는 매칭하지 못한다.


여러 단계의 경로를 한 번에 처리하려면 **Catch-all Routes**를 사용한다. 대괄호 안에 `...`을 붙이면 된다.


```plain text
pages/
└── docs/
    └── [...slug].tsx      → /docs/* (모든 하위 경로)
```


`[...slug].tsx`는 `/docs/a`, `/docs/a/b`, `/docs/a/b/c` 등 모든 하위 경로를 매칭한다.


```typescript
// pages/docs/[...slug].tsx
import { useRouter } from 'next/router';

export default function Docs() {
  const router = useRouter();
  const { slug } = router.query;

  // slug는 배열로 전달됨
  return (
    <div>
      <h1>문서 경로</h1>
      <p>세그먼트: {Array.isArray(slug) ? slug.join(' / ') : slug}</p>
    </div>
  );
}
```


위 코드에서 `slug`는 경로 세그먼트를 배열로 담는다.

- `/docs/introduction` 접속 시: `slug = ["introduction"]`
- `/docs/getting-started/installation` 접속 시: `slug = ["getting-started", "installation"]`
- `/docs/api/hooks/useRouter` 접속 시: `slug = ["api", "hooks", "useRouter"]`

배열의 각 요소가 경로의 각 세그먼트에 해당한다. 이를 활용해 동적으로 컨텐츠를 렌더링하거나 파일 시스템에서 마크다운 파일을 읽어올 수 있다.


### Catch-all Routes의 한계


하지만 `[...slug].tsx`는 최소 하나의 세그먼트가 필요하다. `/docs`에는 매칭되지 않고 `/docs/something`부터 매칭된다.


`/docs`도 같은 컴포넌트로 처리하고 싶다면 두 가지 방법이 있다.

1. `docs/index.tsx`를 별도로 만든다
2. **Optional Catch-all Routes**를 사용한다

## Optional Catch-all Routes


대괄호를 한 번 더 감싸면 Optional Catch-all Routes가 된다.


```plain text
pages/
└── docs/
    └── [[...slug]].tsx    → /docs 및 /docs/* (모든 하위 경로)
```


`[[...slug]].tsx`는 `/docs`도 매칭하고, `/docs/a`, `/docs/a/b` 등 모든 하위 경로도 매칭한다.


```typescript
// pages/docs/[[...slug]].tsx
import { useRouter } from 'next/router';

export default function Docs() {
  const router = useRouter();
  const { slug } = router.query;

  if (!slug) {
    // /docs 경로
    return <h1>문서 홈</h1>;
  }

  // /docs/* 경로
  return (
    <div>
      <h1>문서 경로</h1>
      <p>세그먼트: {slug.join(' / ')}</p>
    </div>
  );
}
```

- `/docs` 접속 시: `slug = undefined`
- `/docs/introduction` 접속 시: `slug = ["introduction"]`
- `/docs/api/hooks` 접속 시: `slug = ["api", "hooks"]`

이렇게 하면 하나의 컴포넌트로 모든 문서 경로를 처리할 수 있다.


## 라우팅 우선순위


여러 라우트 패턴이 동일한 URL에 매칭될 수 있는 경우, Next.js는 다음 우선순위로 라우트를 결정한다.

1. **정적 라우트** (우선순위 가장 높음)
2. **동적 라우트**
3. **Catch-all 라우트** (우선순위 가장 낮음)

```plain text
pages/
├── posts/
│   ├── index.tsx          (1) /posts
│   ├── create.tsx         (2) /posts/create
│   ├── [id].tsx           (3) /posts/:id
│   └── [...slug].tsx      (4) /posts/*
```


위 구조에서:

- `/posts` 접속 시: `index.tsx` 매칭
- `/posts/create` 접속 시: `create.tsx` 매칭 (정적 라우트가 우선)
- `/posts/123` 접속 시: `[id].tsx` 매칭
- `/posts/a/b/c` 접속 시: `[...slug].tsx` 매칭

`create.tsx`가 있다면 `/posts/create`는 `[id].tsx`보다 우선한다. 정적 라우트가 동적 라우트보다 우선순위가 높기 때문이다.


## 404 페이지


존재하지 않는 경로에 접속할 때 표시되는 404 페이지를 커스터마이징할 수 있다. `pages` 폴더 최상위에 `404.tsx` 파일을 만들면 된다.


```typescript
// pages/404.tsx
import Link from 'next/link';

export default function Custom404() {
  return (
    <div>
      <h1>404 - 페이지를 찾을 수 없습니다</h1>
      <p>요청하신 페이지가 존재하지 않습니다.</p>
      <Link href="/">홈으로 돌아가기</Link>
    </div>
  );
}
```


빌드 시 자동으로 정적 페이지로 생성되므로 추가 서버 부하 없이 빠르게 제공된다.


## 참고 자료

- [Next.js 공식 문서 - Pages Router Routing](https://nextjs.org/docs/pages/building-your-application/routing)


Page Router routing 설정하기

Page Router vs. App Router


Next.js에서는 CSS를 사용하는 두 가지 기본 방법을 제공한다. **Global CSS**와 **CSS Modules**다.


## Global CSS


전역 CSS는 애플리케이션 전체에 적용되는 스타일이다. Next.js에서는 `pages/_app.tsx` 파일에서만 Global CSS를 import할 수 있다.


### 왜 `_app.tsx`에서만 가능한가?


일반 컴포넌트나 페이지에서 Global CSS를 import하면 **다른 페이지의 스타일과 충돌**할 수 있다.


예를 들어 다음과 같은 상황을 생각해보자.


```css
/* pages/home.css */
.button {
  background: red;
}
```


```css
/* pages/about.css */
.button {
  background: blue;
}
```


```typescript
// pages/index.tsx
import './home.css';  // ❌ 허용되지 않음

export default function Home() {
  return <button className="button">홈</button>;
}
```


```typescript
// pages/about.tsx
import './about.css';  // ❌ 허용되지 않음

export default function About() {
  return <button className="button">소개</button>;
}
```


위 코드에서 `/` 페이지를 방문한 후 `/about` 페이지로 이동하면, `home.css`가 이미 로드된 상태에서 `about.css`가 추가로 로드된다. 두 CSS 파일 모두 `.button` 클래스를 정의하므로 스타일이 충돌한다.


Next.js는 클라이언트 사이드 네비게이션을 사용하므로, 페이지를 이동해도 **이전 페이지의 CSS가 언로드되지 않는다**. 따라서 모든 페이지의 CSS가 누적되면서 예측 불가능한 스타일 충돌이 발생한다.


### 사용법


`_app.tsx`는 모든 페이지에 공통으로 적용되는 컴포넌트이므로, 여기에서 Global CSS를 import하는 것은 안전하다.


```typescript
// pages/_app.tsx
import '@/styles/globals.css';  // 허용됨
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />;
}
```


```css
/* styles/globals.css */
* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

body {
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
}

a {
  color: inherit;
  text-decoration: none;
}
```


### 언제 사용하는가?


Global CSS는 다음과 같은 경우에 사용한다.

- CSS Reset 또는 Normalize
- 전역 폰트 설정
- 전역 색상 변수
- 모든 페이지에 공통으로 적용되는 기본 스타일

페이지나 컴포넌트별 스타일은 CSS Modules를 사용하는 것이 좋다.


## CSS Modules


CSS Modules는 CSS 파일을 모듈로 import하여 **로컬 스코프**로 사용하는 방법이다. Next.js에 기본으로 내장되어 있어 별도 설정 없이 사용할 수 있다.


### 왜 필요한가?


일반 CSS는 전역 스코프를 사용하므로 클래스명이 충돌할 수 있다.


```css
/* home.css */
.title {
  color: red;
}
```


```css
/* about.css */
.title {
  color: blue;
}
```


두 파일 모두 `.title` 클래스를 정의하므로, 나중에 로드된 스타일이 이전 스타일을 덮어쓴다.


CSS Modules는 각 클래스명을 **유니크한 이름으로 자동 변환**하여 이 문제를 해결한다.


```css
/* 원본 */
.title {
  color: red;
}

/* 빌드 후 실제 클래스명 */
.Home_title__abc123 {
  color: red;
}
```


### 사용법


CSS Modules를 사용하려면 파일명을 `.module.css` 형식으로 만든다.


```css
/* components/Button.module.css */
.button {
  padding: 12px 24px;
  background: #0070f3;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

.button:hover {
  background: #0051cc;
}
```


컴포넌트에서 import하여 사용한다.


```typescript
// components/Button.tsx
import styles from './Button.module.css';

export default function Button({ children }: { children: React.ReactNode }) {
  return <button className={styles.button}>{children}</button>;
}
```


`styles.button`은 빌드 시 `Button_button__abc123`과 같은 유니크한 클래스명으로 변환된다.


### 여러 클래스 사용하기


여러 클래스를 함께 사용하려면 템플릿 리터럴이나 배열을 사용한다.


```css
/* Card.module.css */
.card {
  padding: 20px;
  border: 1px solid #ddd;
  border-radius: 8px;
}

.featured {
  border-color: #0070f3;
  background: #f0f8ff;
}
```


```typescript
// Card.tsx
import styles from './Card.module.css';

export default function Card({ featured }: { featured?: boolean }) {
  return (
    <div className={`${styles.card} ${featured ? styles.featured : ''}`}>
      카드 내용
    </div>
  );
}
```


### 글로벌 클래스와 함께 사용


CSS Modules 내에서 글로벌 클래스를 선택해야 할 때는 `:global` 선택자를 사용한다.


```css
/* Component.module.css */
.wrapper :global(.external-class) {
  color: red;
}
```


## 참고 자료

- [Next.js 공식 문서 - Styling](https://nextjs.org/docs/pages/building-your-application/styling)
- [Next.js 공식 문서 - CSS Modules](https://nextjs.org/docs/pages/building-your-application/styling/css-modules)


Styling


사전에(pre-) 미리 불러온다(fetching).


연결되어 있는 페이지들을 사전에 미리 불러온다. 빠른 페이지 이동을 위해 미리 데이터를 로드해둔다.


## 왜 Prefetching이 필요한가?


생각해보면 이 기능은 뭔가 이상하다. 초기 접속 이후의 활동들은 서버에게 별도 추가 요청 없이 브라우저에서 직접 React 컴포넌트를 교체하는 방식으로 처리한다. 그렇기 때문에 페이지를 이동하더라도 브라우저가 서버에게 추가 리소스를 요구하지 않는 것으로 알고 있는데 prefetching은 왜 있는가?


### Code Splitting


Next.js는 모든 JavaScript 코드를 자동으로 페이지별로 분리(splitting)해서 저장한다. **모든 코드가 전달되는 것이 아니라 현재 페이지의 번들만 전달된다**. `/search`로 접속하면 search 페이지의 번들만 전달된다.


이렇게 하는 이유는 파일 크기를 줄이기 위해서다. 모든 페이지의 번들을 한 번에 전달하면 용량이 커져서 하이드레이션이 늦어진다. 그럼 **TTI(Time To Interactive)가 최종적으로 늦어진다.


따라서 페이지를 이동할 때는 해당 페이지의 번들을 새로 요청해야 한다. Prefetching은 페이지 이동 요청 전에 미리 번들을 불러오는 방식이다.


## Prefetching 확인하기


### 개발 모드에서는 작동하지 않는다


`npm run dev`로 실행하면 prefetching이 작동하지 않는다. 페이지를 이동할 때마다 번들을 매번 불러온다.


Prefetching 동작을 제대로 확인하려면 **build 후 production 모드**로 실행해야 한다. `npm run build`를 하면 페이지별로 빌드 결과가 출력된다.


```plain text
Route (pages)                             Size     First Load JS
┌ ○ /                                     256 B          82.7 kB
├   /_app                                 0 B            82.5 kB
├ ○ /404                                  180 B          82.7 kB
├ ƒ /api/hello                            0 B            82.5 kB
├ ○ /book/[id]                            300 B          82.8 kB
└ ○ /search                               296 B          82.8 kB
+ First Load JS shared by all             82.5 kB
  ├ chunks/framework-64ad27b21261a9ce.js  44.8 kB
  ├ chunks/main-a2464d6d00b134e7.js       34 kB
  └ other shared chunks (total)           3.61 kB

○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand
```


위 결과에서 각 페이지별로 번들이 분리(splitting)되어 있는 것을 확인할 수 있다. 각 페이지는 독립적인 크기를 갖고 있으며, 공통 코드는 "shared by all"로 분리되어 있다.


### Production 모드에서 확인


Code splitting이 되는 것을 확인했다. `npm run start`를 하면 `localhost:3000`에서 네트워크 탭을 열었을 때 많은 요청이 일어난다. search, book에 필요한 페이지들도 모두 prefetching 되어 있다.


브라우저 개발자 도구의 Network 탭을 열고 페이지를 로드하면, 현재 페이지뿐만 아니라 화면에 보이는 Link 컴포넌트가 가리키는 페이지들의 번들도 함께 다운로드된다.


## Link 컴포넌트의 자동 Prefetching


Link 컴포넌트로 구현된 링크는 자동으로 prefetching이 이루어진다.


`Link` 컴포넌트는 기본적으로 **viewport에 보이는 링크를 자동으로 prefetch**한다. 사용자가 링크를 클릭하기 전에 미리 페이지를 로드해두기 때문에 즉각적인 페이지 전환이 가능하다.


```typescript
import Link from 'next/link';

export default function Navigation() {
  return (
    <nav>
      {/* 이 링크들은 viewport에 보이면 자동으로 prefetch된다 */}
      <Link href="/">홈</Link>
      <Link href="/about">소개</Link>
      <Link href="/blog">블로그</Link>
    </nav>
  );
}
```


이 기능은 **프로덕션 빌드에서만 동작**하며, 개발 모드에서는 작동하지 않는다.


## 프로그래매틱 네비게이션의 수동 Prefetching


프로그래매틱하게 구현된 네비게이션은 페이지 이동 시 번들을 다시 요청한다. 여기에서도 prefetching을 하고 싶다면 컴포넌트 마운트 시 router 객체의 메서드를 통해 수동으로 prefetching할 수 있다.


```typescript
import { useRouter } from 'next/router';
import { useEffect } from 'react';

export default function Page() {
  const router = useRouter();

  useEffect(() => {
    // 컴포넌트 마운트 시 /test 페이지를 미리 로드
    router.prefetch('/test');
  }, []);

  const handleClick = () => {
    // 이미 prefetch되어 있으므로 즉시 이동
    router.push('/test');
  };

  return <button onClick={handleClick}>테스트 페이지로 이동</button>;
}
```


`router.prefetch()`를 사용하면 특정 페이지의 번들을 미리 로드할 수 있다. 이후 `router.push()`로 페이지 이동 시 즉각적인 전환이 가능하다.


### 조건부 Prefetching


특정 조건에서만 prefetch하고 싶을 때도 사용할 수 있다.


```typescript
import { useRouter } from 'next/router';
import { useEffect } from 'react';

export default function Dashboard({ user }) {
  const router = useRouter();

  useEffect(() => {
    // 관리자일 경우에만 admin 페이지를 prefetch
    if (user.isAdmin) {
      router.prefetch('/admin');
    }
  }, [user.isAdmin]);

  return <div>대시보드</div>;
}
```


## Prefetching 비활성화


Prefetching을 하고 싶지 않다면 `prefetch={false}`를 설정한다.


대용량 페이지나 데이터가 자주 변경되는 페이지의 경우 불필요한 네트워크 요청을 줄이고 싶을 수 있다. `Link` 컴포넌트에서 `prefetch={false}`를 설정하면 자동 prefetch를 비활성화할 수 있다.


```typescript
import Link from 'next/link';

export default function Navigation() {
  return (
    <nav>
      {/* 일반 페이지는 prefetch */}
      <Link href="/">홈</Link>

      {/* 대용량 페이지는 prefetch 비활성화 */}
      <Link href="/heavy-page" prefetch={false}>
        대용량 페이지
      </Link>

      {/* 자주 변경되는 페이지도 prefetch 비활성화 */}
      <Link href="/live-data" prefetch={false}>
        실시간 데이터
      </Link>
    </nav>
  );
}
```


## 정리

- **Code Splitting**: Next.js는 페이지별로 번들을 자동으로 분리한다
- **Prefetching**: 페이지 이동 전에 미리 번들을 로드하여 빠른 전환을 가능하게 한다
- **Link 컴포넌트**: viewport에 보이는 링크를 자동으로 prefetch (프로덕션 모드에서만)
- **router.prefetch()**: 수동으로 특정 페이지를 미리 로드
- **prefetch={false}**: Link 컴포넌트의 자동 prefetch를 비활성화
- **개발 모드**: prefetching이 작동하지 않으므로 테스트는 production 모드에서

## 참고 자료

- [Next.js 공식 문서 - Link prefetching](https://nextjs.org/docs/pages/api-reference/components/link#prefetch)
- [[Navigating]] - 페이지 간 이동 방법


Prefetching


Next.js에서 페이지 간 이동하는 방법을 다룬다. Link 컴포넌트와 useRouter 훅을 사용하여 클라이언트 사이드 네비게이션을 구현한다.


## a 태그 vs Link 컴포넌트


HTML의 `<a>` 태그는 매번 서버에 새로운 페이지를 요청한다. 페이지 전체가 새로고침되며 JavaScript 상태가 초기화된다.


```typescript
// 느린 방식 - 전체 페이지 새로고침
<a href="/about">소개</a>
```


Next.js의 `Link` 컴포넌트는 **클라이언트 사이드 네비게이션**을 제공한다. 페이지 전체를 새로고침하지 않고 필요한 부분만 업데이트한다.


```typescript
// 빠른 방식 - 클라이언트 사이드 네비게이션
import Link from 'next/link';

<Link href="/about">소개</Link>
```


`Link` 컴포넌트를 사용하면 다음과 같은 장점이 있다.

- 페이지 전환이 즉각적이다
- JavaScript 상태가 유지된다
- viewport에 보이는 링크를 미리 로드한다 (자세한 내용은 [[prefetching]] 참조)
- 브라우저 히스토리가 정상적으로 동작한다

## Link 컴포넌트


`next/link`에서 제공하는 `Link` 컴포넌트는 페이지 간 이동의 기본이다.


### 기본 사용법


```typescript
import Link from 'next/link';

export default function Navigation() {
  return (
    <header>
      <Link href="/">index</Link>
      &nbsp;
      <Link href="/search">search</Link>
      &nbsp;
      <Link href="/book/1">book/1</Link>
    </header>
  );
}
```


`href` prop에 이동할 경로를 문자열로 전달한다.


### 동적 경로에 Link 사용


동적 경로는 문자열 보간이나 객체 형태로 전달할 수 있다.


```typescript
import Link from 'next/link';

export default function PostList() {
  const posts = [
    { id: 1, title: '첫 번째 포스트' },
    { id: 2, title: '두 번째 포스트' },
    { id: 3, title: '세 번째 포스트' },
  ];

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          {/* 문자열 보간 방식 */}
          <Link href={`/posts/${post.id}`}>{post.title}</Link>
        </li>
      ))}
    </ul>
  );
}
```


객체 형태로도 전달할 수 있다.


```typescript
<Link
  href={{
    pathname: '/posts/[id]',
    query: { id: post.id },
  }}
>
  {post.title}
</Link>
```


Query String도 함께 전달할 수 있다.


```typescript
// 문자열 방식
<Link href="/posts/1?comments=true">포스트 1</Link>

// 객체 방식
<Link
  href={{
    pathname: '/posts/[id]',
    query: { id: 1, comments: 'true' },
  }}
>
  포스트 1
</Link>
```


### 외부 링크


외부 링크는 일반 `<a>` 태그를 사용한다.


```typescript
{/* 외부 링크는 a 태그 사용 */}
<a href="<https://github.com>" target="_blank" rel="noopener noreferrer">
  GitHub
</a>

{/* 내부 링크는 Link 컴포넌트 사용 */}
<Link href="/about">소개</Link>
```


## useRouter 훅


`useRouter` 훅은 현재 라우터 정보에 접근하고 프로그래매틱하게 네비게이션을 제어할 수 있게 한다.

> 주의: next/router 사용useRouter는 next/router에서 import 해야 한다. next/navigation의 useRouter는 App Router 전용이다.

```typescript
import { useRouter } from 'next/router';

export default function Page() {
  const router = useRouter();

  console.log(router.pathname);  // 현재 경로 패턴 (예: /posts/[id])
  console.log(router.asPath);    // 브라우저 주소창의 전체 경로 (예: /posts/123?sort=latest)
  console.log(router.query);     // 쿼리 파라미터 객체 (예: { id: '123', sort: 'latest' })

  return <div>페이지</div>;
}
```


### router 주요 속성

- `pathname`: 현재 페이지의 경로 패턴 (동적 세그먼트는 대괄호 형태)
- `asPath`: 실제 브라우저에 표시되는 전체 경로
- `query`: URL 파라미터와 Query String을 담은 객체
- `route`: `pathname`과 동일

### Query String 접근


`router.query`로 URL의 모든 파라미터에 접근할 수 있다.


```typescript
// pages/search.tsx
import { useRouter } from 'next/router';

export default function Search() {
  const router = useRouter();
  const { q, sort } = router.query;

  return (
    <div>
      <h1>검색어: {q}</h1>
      <p>정렬: {sort}</p>
    </div>
  );
}
```


`/search?q=nextjs&sort=latest`에 접속하면 `q`는 `"nextjs"`, `sort`는 `"latest"`가 된다.


동적 라우팅 파라미터와 Query String이 모두 `router.query`에 통합된다.


```typescript
// pages/posts/[id].tsx
import { useRouter } from 'next/router';

export default function Post() {
  const router = useRouter();
  const { id, comments } = router.query;

  return (
    <div>
      <h1>포스트 ID: {id}</h1>
      {comments && <p>댓글 표시 모드</p>}
    </div>
  );
}
```


`/posts/123?comments=true`에 접속하면 `id`는 `"123"`, `comments`는 `"true"`가 된다.


## 프로그래매틱 네비게이션


특정 조건이 충족되었을 때 코드로 페이지를 이동할 수 있다. `router.push()`와 `router.replace()`를 사용한다.


### router.push()


`router.push()`는 새로운 URL을 브라우저 히스토리에 추가하고 이동한다. 뒤로가기 버튼으로 이전 페이지로 돌아갈 수 있다.


```typescript
import { useRouter } from 'next/router';

export default function LoginPage() {
  const router = useRouter();

  const handleLogin = async () => {
    // 로그인 로직...
    const success = true;

    if (success) {
      // 로그인 성공 후 대시보드로 이동
      router.push('/dashboard');
    }
  };

  return <button onClick={handleLogin}>로그인</button>;
}
```


Query String이나 동적 세그먼트도 전달할 수 있다.


```typescript
// 문자열 형태
router.push('/posts/123?sort=latest');

// 객체 형태
router.push({
  pathname: '/posts/[id]',
  query: { id: '123', sort: 'latest' },
});
```


### router.replace()


`router.replace()`는 현재 히스토리를 대체한다. 뒤로가기를 눌렀을 때 이전 페이지로 돌아가지 않는다.


```typescript
const handleRedirect = () => {
  // 히스토리에 추가하지 않고 대체
  router.replace('/new-page');
};
```


로그인 후 리다이렉트처럼 사용자가 뒤로가기로 돌아가지 못하게 하고 싶을 때 사용한다.


```typescript
import { useRouter } from 'next/router';

export default function LoginPage() {
  const router = useRouter();

  const handleLogin = async () => {
    // 로그인 로직...
    const success = true;

    if (success) {
      // 뒤로가기로 로그인 페이지로 돌아가지 않도록 replace 사용
      router.replace('/dashboard');
    }
  };

  return <button onClick={handleLogin}>로그인</button>;
}
```


### router.back()


브라우저 히스토리에서 뒤로 이동한다.


```typescript
import { useRouter } from 'next/router';

export default function PostDetail() {
  const router = useRouter();

  return (
    <div>
      <button onClick={() => router.back()}>뒤로 가기</button>
      <h1>포스트 상세</h1>
    </div>
  );
}
```


### router.reload()


현재 페이지를 새로고침한다. 서버에서 다시 페이지를 가져온다.


```typescript
const handleReload = () => {
  router.reload();
};
```


## push vs replace 비교


```typescript
import { useRouter } from 'next/router';

export default function Example() {
  const router = useRouter();

  return (
    <div>
      {/* push: 히스토리에 추가, 뒤로가기 가능 */}
      <button onClick={() => router.push('/page-a')}>
        Page A로 이동 (push)
      </button>

      {/* replace: 히스토리 대체, 뒤로가기로 돌아올 수 없음 */}
      <button onClick={() => router.replace('/page-b')}>
        Page B로 이동 (replace)
      </button>

      {/* back: 이전 페이지로 */}
      <button onClick={() => router.back()}>
        뒤로 가기
      </button>
    </div>
  );
}
```


## 참고 자료

- [Next.js 공식 문서 - next/link](https://nextjs.org/docs/pages/api-reference/components/link)
- [Next.js 공식 문서 - useRouter](https://nextjs.org/docs/pages/api-reference/functions/use-router)


Navigating


Next.js에서 서버 사이드 API 엔드포인트를 만들 수 있는 기능이다. `pages/api` 폴더 안에 파일을 생성하면 자동으로 API 엔드포인트가 된다.


## 왜 필요한가?


프론트엔드 애플리케이션을 만들 때 종종 서버와 통신할 API가 필요하다. 일반적으로는 별도의 백엔드 서버(Express, Django 등)를 구축하지만, Next.js는 **같은 프로젝트 내에서 API를 만들 수 있다**.


이렇게 하면 다음과 같은 장점이 있다.

- 별도의 백엔드 서버 없이 API를 만들 수 있다
- 같은 코드베이스에서 프론트엔드와 백엔드를 관리할 수 있다
- 배포가 간단하다 (하나의 프로젝트로 배포)
- TypeScript 타입을 공유할 수 있다

간단한 API가 필요한 경우나, 서버리스 함수로 충분한 경우에 유용하다.


## 기본 구조


`pages/api` 폴더 안에 파일을 만들면 자동으로 API 엔드포인트가 된다.


```plain text
pages/
└── api/
    ├── hello.ts         → /api/hello
    ├── users.ts         → /api/users
    └── posts/
        └── [id].ts      → /api/posts/:id
```


파일 이름이 곧 API 경로가 된다. 페이지 라우팅과 동일한 방식이다.


## 기본 핸들러 작성


API Route는 `handler` 함수를 default export 해야 한다.


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

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


`handler` 함수는 두 개의 인자를 받는다.

- `req`: HTTP 요청 정보를 담은 객체
- `res`: HTTP 응답을 보내는 객체

위 코드는 `/api/hello`로 요청이 오면 `{ message: 'Hello from API' }` JSON을 200 상태 코드와 함께 응답한다.


## HTTP 메서드 처리


`req.method`로 HTTP 메서드를 확인하여 다르게 처리할 수 있다.


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

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method === 'GET') {
    // 사용자 목록 조회
    res.status(200).json({ users: ['Alice', 'Bob'] });
  } else if (req.method === 'POST') {
    // 새 사용자 생성
    const { name } = req.body;
    res.status(201).json({ message: `Created user: ${name}` });
  } else {
    // 지원하지 않는 메서드
    res.status(405).json({ message: 'Method not allowed' });
  }
}
```


일반적인 HTTP 메서드는 다음과 같다.

- `GET`: 데이터 조회
- `POST`: 데이터 생성
- `PUT`: 데이터 전체 수정
- `PATCH`: 데이터 부분 수정
- `DELETE`: 데이터 삭제

## Request 처리


### Query 파라미터


URL의 쿼리 파라미터는 `req.query`로 접근한다.


```typescript
// pages/api/search.ts
export default function handler(req: NextApiRequest, res: NextApiResponse) {
  const { q, page } = req.query;

  res.status(200).json({
    query: q,
    page: page || '1'
  });
}
```


`/api/search?q=nextjs&page=2`로 요청하면 `q`는 `"nextjs"`, `page`는 `"2"`가 된다.


### Request Body


POST, PUT 등의 요청에서 본문 데이터는 `req.body`로 접근한다.


```typescript
// pages/api/posts.ts
export default function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method === 'POST') {
    const { title, content } = req.body;

    // 데이터베이스에 저장하는 로직...

    res.status(201).json({
      id: 1,
      title,
      content,
      createdAt: new Date().toISOString()
    });
  } else {
    res.status(405).json({ message: 'Method not allowed' });
  }
}
```


클라이언트에서 JSON으로 요청을 보내면 Next.js가 자동으로 파싱해준다.


### Cookies


쿠키는 `req.cookies`로 접근한다.


```typescript
export default function handler(req: NextApiRequest, res: NextApiResponse) {
  const token = req.cookies.token;

  if (!token) {
    res.status(401).json({ message: 'Unauthorized' });
    return;
  }

  res.status(200).json({ message: 'Authenticated' });
}
```


## Response 처리


### 상태 코드


`res.status()`로 HTTP 상태 코드를 설정한다.


```typescript
// 성공
res.status(200).json({ success: true });

// 생성됨
res.status(201).json({ id: 1 });

// 잘못된 요청
res.status(400).json({ error: 'Bad request' });

// 인증 필요
res.status(401).json({ error: 'Unauthorized' });

// 권한 없음
res.status(403).json({ error: 'Forbidden' });

// 찾을 수 없음
res.status(404).json({ error: 'Not found' });

// 서버 오류
res.status(500).json({ error: 'Internal server error' });
```


### JSON 응답


`res.json()`으로 JSON 응답을 보낸다.


```typescript
export default function handler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({
    name: 'John Doe',
    age: 30,
    hobbies: ['reading', 'coding']
  });
}
```


### 리다이렉트


`res.redirect()`로 다른 경로로 리다이렉트할 수 있다.


```typescript
export default function handler(req: NextApiRequest, res: NextApiResponse) {
  res.redirect(307, '/api/new-endpoint');
}
```


## 동적 API 라우트


페이지 라우팅과 마찬가지로 동적 세그먼트를 사용할 수 있다.


### 단일 동적 세그먼트


```typescript
// pages/api/posts/[id].ts
export default function handler(req: NextApiRequest, res: NextApiResponse) {
  const { id } = req.query;

  if (req.method === 'GET') {
    // ID로 포스트 조회
    res.status(200).json({
      id,
      title: `Post ${id}`,
      content: 'Content here'
    });
  } else if (req.method === 'DELETE') {
    // ID로 포스트 삭제
    res.status(200).json({ message: `Deleted post ${id}` });
  }
}
```


`/api/posts/123`으로 요청하면 `id`는 `"123"`이 된다.


### Catch-all 라우트


```typescript
// pages/api/posts/[...slug].ts
export default function handler(req: NextApiRequest, res: NextApiResponse) {
  const { slug } = req.query;

  // slug는 배열로 전달됨
  res.status(200).json({
    path: slug
  });
}
```

- `/api/posts/a` → `slug = ["a"]`
- `/api/posts/a/b` → `slug = ["a", "b"]`
- `/api/posts/a/b/c` → `slug = ["a", "b", "c"]`

## 환경 변수 사용


API Route는 서버에서만 실행되므로 환경 변수를 안전하게 사용할 수 있다.


```typescript
// pages/api/secret.ts
export default function handler(req: NextApiRequest, res: NextApiResponse) {
  const apiKey = process.env.SECRET_API_KEY;

  // 외부 API 호출 등에 사용
  res.status(200).json({ message: 'Success' });
}
```


`.env.local` 파일에 환경 변수를 정의한다.


```plain text
SECRET_API_KEY=your-secret-key
DATABASE_URL=postgresql://...
```


환경 변수는 클라이언트 번들에 포함되지 않으므로 민감한 정보를 안전하게 사용할 수 있다.


## 설정 옵션


API Route의 동작을 커스터마이징할 수 있다.


### Body Parser 설정


기본적으로 Next.js는 요청 본문을 자동으로 파싱한다. 이를 비활성화하거나 크기 제한을 설정할 수 있다.


```typescript
export const config = {
  api: {
    bodyParser: {
      sizeLimit: '1mb', // 요청 본문 크기 제한
    },
  },
};

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  // 핸들러 로직
}
```


Body parser를 완전히 비활성화하려면 다음과 같이 한다.


```typescript
export const config = {
  api: {
    bodyParser: false,
  },
};
```


파일 업로드나 스트리밍을 처리할 때 유용하다.


### 실행 시간 제한


서버리스 환경에서 실행 시간을 제한할 수 있다.


```typescript
export const config = {
  api: {
    maxDuration: 5, // 최대 5초
  },
};
```


## 주의사항


### 클라이언트 번들에 포함되지 않는다


API Routes의 코드는 **클라이언트 번들에 포함되지 않는다**. 서버에서만 실행된다.


따라서 다음을 안전하게 사용할 수 있다.

- 데이터베이스 쿼리
- 환경 변수
- 서버 전용 라이브러리
- 비밀 키

### CORS 처리


다른 도메인에서 API를 호출해야 한다면 CORS 헤더를 설정해야 한다.


```typescript
export default function handler(req: NextApiRequest, res: NextApiResponse) {
  // CORS 헤더 설정
  res.setHeader('Access-Control-Allow-Origin', '*');
  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');

  // Preflight 요청 처리
  if (req.method === 'OPTIONS') {
    res.status(200).end();
    return;
  }

  // 실제 로직
  res.status(200).json({ message: 'Hello' });
}
```


### 정적 생성과 함께 사용할 수 없다


API Routes는 서버에서 실행되므로 정적 사이트 생성(SSG) 시에는 호출할 수 없다. `getStaticProps`에서 API Route를 호출하면 안 된다.


대신 데이터를 직접 가져오는 로직을 공유한다.


```typescript
// lib/data.ts
export async function getProducts() {
  // 데이터베이스 쿼리
  return products;
}

// pages/api/products.ts
import { getProducts } from '@/lib/data';

export default async function handler(req, res) {
  const products = await getProducts();
  res.status(200).json(products);
}

// pages/index.tsx
import { getProducts } from '@/lib/data';

export async function getStaticProps() {
  const products = await getProducts(); // API Route 호출 X, 직접 호출 O
  return { props: { products } };
}
```


## 참고 자료

- [Next.js 공식 문서 - API Routes](https://nextjs.org/docs/pages/building-your-application/routing/api-routes)


API Routes


Next.js의 Page Router는 `pages` 폴더 내의 파일 구조를 기반으로 자동으로 라우팅을 생성하는 시스템이다. 별도의 라우팅 설정 파일 없이 파일과 폴더만으로 URL 경로를 정의할 수 있다.

> Page Router vs App Router  
> Next.js 13부터 App Router가 도입되었지만, Page Router는 여전히 안정적이고 널리 사용된다. App Router는 Server Components를 기본으로 하는 새로운 패러다임이며, Page Router는 기존의 Client-side Navigation을 중심으로 한다.

## 기본 라우팅


`pages` 폴더 내의 파일이 자동으로 라우트가 된다. 파일명이 곧 URL 경로다.


```plain text
pages/
├── index.tsx          → /
├── about.tsx          → /about
├── contact.tsx        → /contact
└── products.tsx       → /products
```


위 구조에서 `index.tsx`는 루트 경로 `/`에 매핑되고, `about.tsx`는 `/about` 경로에 매핑된다.


```typescript
// pages/index.tsx
export default function Home() {
  return <h1>홈 페이지</h1>;
}
```


```typescript
// pages/about.tsx
export default function About() {
  return <h1>소개 페이지</h1>;
}
```


각 파일은 기본적으로 React 컴포넌트를 default export 해야 한다. Next.js는 이 컴포넌트를 자동으로 페이지로 렌더링한다.


## 중첩 라우팅


폴더를 사용하면 중첩된 경로를 만들 수 있다.


```plain text
pages/
├── index.tsx              → /
├── blog/
│   ├── index.tsx          → /blog
│   ├── first-post.tsx     → /blog/first-post
│   └── second-post.tsx    → /blog/second-post
└── products/
    ├── index.tsx          → /products
    └── electronics.tsx    → /products/electronics
```


폴더 내의 `index.tsx`는 해당 폴더 경로의 기본 페이지가 된다. 예를 들어 `blog/index.tsx`는 `/blog` 경로에 매핑된다.


```typescript
// pages/blog/index.tsx
export default function Blog() {
  return <h1>블로그 목록</h1>;
}
```


```typescript
// pages/blog/first-post.tsx
export default function FirstPost() {
  return <h1>첫 번째 포스트</h1>;
}
```


이렇게 폴더 구조만으로 직관적인 URL 계층을 구성할 수 있다.


## 동적 라우팅 (URL Parameter)


동적 경로를 갖는 페이지를 생성하려면 파일명을 대괄호로 감싸면 된다. `[id].tsx`와 같이 작성하면 해당 부분이 동적 세그먼트가 된다.


```plain text
pages/
└── posts/
    ├── index.tsx          → /posts
    └── [id].tsx           → /posts/:id
```


`[id].tsx` 파일은 `/posts/1`, `/posts/abc`, `/posts/hello` 등 모든 경로에 매칭된다.


```typescript
// pages/posts/[id].tsx
import { useRouter } from 'next/router';

export default function Post() {
  const router = useRouter();
  const { id } = router.query;

  return <h1>포스트 ID: {id}</h1>;
}
```


위 코드에서 `useRouter` 훅을 통해 URL의 동적 파라미터에 접근할 수 있다. `router.query` 객체에서 파일명에 정의한 `id`를 구조 분해 할당으로 가져온다.


사용자가 `/posts/123`에 접속하면 `id`는 `"123"`이 되고, `/posts/hello`에 접속하면 `id`는 `"hello"`가 된다.


### 여러 동적 세그먼트


여러 동적 세그먼트를 조합할 수도 있다.


```plain text
pages/
└── posts/
    └── [category]/
        └── [id].tsx       → /posts/:category/:id
```


```typescript
// pages/posts/[category]/[id].tsx
import { useRouter } from 'next/router';

export default function Post() {
  const router = useRouter();
  const { category, id } = router.query;

  return (
    <div>
      <h1>카테고리: {category}</h1>
      <p>포스트 ID: {id}</p>
    </div>
  );
}
```


`/posts/tech/123`에 접속하면 `category`는 `"tech"`, `id`는 `"123"`이 된다.


## Query String


Query String은 페이지 경로에 영향을 주지 않으며, `?` 뒤에 오는 파라미터들을 의미한다. 예를 들어 `/search?q=nextjs&sort=latest`에서 `q`와 `sort`가 Query String이다.


별도의 설정 없이 `useRouter` 훅으로 접근할 수 있다.

> 주의: next/router 사용useRouter는 next/router에서 import 해야 한다. next/navigation의 useRouter는 App Router 전용이므로 Page Router에서는 사용할 수 없다.

```typescript
// pages/search.tsx
import { useRouter } from 'next/router';

export default function Search() {
  const router = useRouter();
  const { q, sort } = router.query;

  return (
    <div>
      <h1>검색어: {q}</h1>
      <p>정렬: {sort}</p>
    </div>
  );
}
```


사용자가 `/search?q=nextjs&sort=latest`에 접속하면 `q`는 `"nextjs"`, `sort`는 `"latest"`가 된다.


Query String은 동적 라우팅 파라미터와 함께 사용할 수도 있다. 모든 파라미터는 `router.query`에 통합된다.


```typescript
// pages/posts/[id].tsx
import { useRouter } from 'next/router';

export default function Post() {
  const router = useRouter();
  const { id, comments } = router.query;

  return (
    <div>
      <h1>포스트 ID: {id}</h1>
      {comments && <p>댓글 표시 모드</p>}
    </div>
  );
}
```


`/posts/123?comments=true`에 접속하면 `id`는 `"123"`, `comments`는 `"true"`가 된다.


## Catch-all Routes


단일 동적 세그먼트는 한 단계의 경로만 매칭한다. `/posts/[id].tsx`는 `/posts/123`은 매칭하지만 `/posts/123/comments`는 매칭하지 못한다.


여러 단계의 경로를 한 번에 처리하려면 **Catch-all Routes**를 사용한다. 대괄호 안에 `...`을 붙이면 된다.


```plain text
pages/
└── docs/
    └── [...slug].tsx      → /docs/* (모든 하위 경로)
```


`[...slug].tsx`는 `/docs/a`, `/docs/a/b`, `/docs/a/b/c` 등 모든 하위 경로를 매칭한다.


```typescript
// pages/docs/[...slug].tsx
import { useRouter } from 'next/router';

export default function Docs() {
  const router = useRouter();
  const { slug } = router.query;

  // slug는 배열로 전달됨
  return (
    <div>
      <h1>문서 경로</h1>
      <p>세그먼트: {Array.isArray(slug) ? slug.join(' / ') : slug}</p>
    </div>
  );
}
```


위 코드에서 `slug`는 경로 세그먼트를 배열로 담는다.

- `/docs/introduction` 접속 시: `slug = ["introduction"]`
- `/docs/getting-started/installation` 접속 시: `slug = ["getting-started", "installation"]`
- `/docs/api/hooks/useRouter` 접속 시: `slug = ["api", "hooks", "useRouter"]`

배열의 각 요소가 경로의 각 세그먼트에 해당한다. 이를 활용해 동적으로 컨텐츠를 렌더링하거나 파일 시스템에서 마크다운 파일을 읽어올 수 있다.


### Catch-all Routes의 한계


하지만 `[...slug].tsx`는 최소 하나의 세그먼트가 필요하다. `/docs`에는 매칭되지 않고 `/docs/something`부터 매칭된다.


`/docs`도 같은 컴포넌트로 처리하고 싶다면 두 가지 방법이 있다.

1. `docs/index.tsx`를 별도로 만든다
2. **Optional Catch-all Routes**를 사용한다

## Optional Catch-all Routes


대괄호를 한 번 더 감싸면 Optional Catch-all Routes가 된다.


```plain text
pages/
└── docs/
    └── [[...slug]].tsx    → /docs 및 /docs/* (모든 하위 경로)
```


`[[...slug]].tsx`는 `/docs`도 매칭하고, `/docs/a`, `/docs/a/b` 등 모든 하위 경로도 매칭한다.


```typescript
// pages/docs/[[...slug]].tsx
import { useRouter } from 'next/router';

export default function Docs() {
  const router = useRouter();
  const { slug } = router.query;

  if (!slug) {
    // /docs 경로
    return <h1>문서 홈</h1>;
  }

  // /docs/* 경로
  return (
    <div>
      <h1>문서 경로</h1>
      <p>세그먼트: {slug.join(' / ')}</p>
    </div>
  );
}
```

- `/docs` 접속 시: `slug = undefined`
- `/docs/introduction` 접속 시: `slug = ["introduction"]`
- `/docs/api/hooks` 접속 시: `slug = ["api", "hooks"]`

이렇게 하면 하나의 컴포넌트로 모든 문서 경로를 처리할 수 있다.


## Link 컴포넌트


Next.js에서 페이지 간 이동은 `next/link`의 `Link` 컴포넌트를 사용한다. HTML의 `<a>` 태그와 달리 **클라이언트 사이드 네비게이션**을 제공한다.


```typescript
import Link from 'next/link';

export default function Nav() {
  return (
    <nav>
      <Link href="/">홈</Link>
      <Link href="/about">소개</Link>
      <Link href="/blog">블로그</Link>
    </nav>
  );
}
```


`Link` 컴포넌트를 사용하면 페이지 전체를 새로고침하지 않고 필요한 부분만 업데이트한다. 이를 통해 빠른 페이지 전환과 상태 유지가 가능하다.


### 동적 경로에 Link 사용


동적 경로는 문자열 보간이나 객체 형태로 전달할 수 있다.


```typescript
import Link from 'next/link';

export default function PostList() {
  const posts = [
    { id: 1, title: '첫 번째 포스트' },
    { id: 2, title: '두 번째 포스트' },
  ];

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          <Link href={`/posts/${post.id}`}>{post.title}</Link>
        </li>
      ))}
    </ul>
  );
}
```


객체 형태로도 전달할 수 있다.


```typescript
<Link
  href={{
    pathname: '/posts/[id]',
    query: { id: post.id },
  }}
>
  {post.title}
</Link>
```


### Prefetching


`Link` 컴포넌트는 기본적으로 viewport에 보이는 링크를 **자동으로 prefetch**한다. 사용자가 링크를 클릭하기 전에 미리 페이지를 로드해두기 때문에 즉각적인 페이지 전환이 가능하다.


프로덕션 빌드에서만 동작하며, `prefetch={false}`로 비활성화할 수 있다.


```typescript
<Link href="/about" prefetch={false}>
  소개
</Link>
```


## useRouter 훅


`useRouter` 훅은 현재 라우터 정보에 접근하고 프로그래매틱하게 네비게이션을 제어할 수 있게 한다.


```typescript
import { useRouter } from 'next/router';

export default function Page() {
  const router = useRouter();

  console.log(router.pathname);  // 현재 경로 (예: /posts/[id])
  console.log(router.asPath);    // 브라우저에 표시되는 전체 경로 (예: /posts/123?sort=latest)
  console.log(router.query);     // 쿼리 파라미터 객체 (예: { id: '123', sort: 'latest' })

  return <div>페이지</div>;
}
```


주요 속성은 다음과 같다.

- `pathname`: 현재 페이지의 경로 패턴 (동적 세그먼트는 대괄호 형태로 표시됨)
- `asPath`: 실제 브라우저에 표시되는 전체 경로
- `query`: URL 파라미터와 Query String을 담은 객체
- `route`: `pathname`과 동일

## 프로그래매틱 네비게이션


`Link` 컴포넌트 외에 코드로 페이지를 이동할 수 있다. `router.push()`와 `router.replace()`를 사용한다.


### router.push()


`router.push()`는 새로운 URL을 브라우저 히스토리에 추가하고 이동한다.


```typescript
import { useRouter } from 'next/router';

export default function LoginPage() {
  const router = useRouter();

  const handleLogin = async () => {
    // 로그인 로직...

    // 로그인 성공 후 대시보드로 이동
    router.push('/dashboard');
  };

  return <button onClick={handleLogin}>로그인</button>;
}
```


Query String이나 동적 세그먼트도 전달할 수 있다.


```typescript
// 문자열 형태
router.push('/posts/123?sort=latest');

// 객체 형태
router.push({
  pathname: '/posts/[id]',
  query: { id: '123', sort: 'latest' },
});
```


### router.replace()


`router.replace()`는 현재 히스토리를 대체한다. 뒤로가기를 눌렀을 때 이전 페이지로 돌아가지 않는다.


```typescript
const handleRedirect = () => {
  // 히스토리에 추가하지 않고 대체
  router.replace('/new-page');
};
```


로그인 후 리다이렉트처럼 사용자가 뒤로가기로 돌아가지 못하게 하고 싶을 때 유용하다.


### 기타 메서드

- `router.back()`: 브라우저 히스토리에서 뒤로 이동
- `router.reload()`: 현재 페이지 새로고침
- `router.prefetch(url)`: 특정 페이지를 미리 로드

## 라우팅 우선순위


여러 라우트 패턴이 동일한 URL에 매칭될 수 있는 경우, Next.js는 다음 우선순위로 라우트를 결정한다.

1. **정적 라우트** (우선순위 가장 높음)
2. **동적 라우트**
3. **Catch-all 라우트** (우선순위 가장 낮음)

```plain text
pages/
├── posts/
│   ├── index.tsx          (1) /posts
│   ├── create.tsx         (2) /posts/create
│   ├── [id].tsx           (3) /posts/:id
│   └── [...slug].tsx      (4) /posts/*
```


위 구조에서:

- `/posts` 접속 시: `index.tsx` 매칭
- `/posts/create` 접속 시: `create.tsx` 매칭 (정적 라우트가 우선)
- `/posts/123` 접속 시: `[id].tsx` 매칭
- `/posts/a/b/c` 접속 시: `[...slug].tsx` 매칭

`create.tsx`가 있다면 `/posts/create`는 `[id].tsx`보다 우선한다. 정적 라우트가 동적 라우트보다 우선순위가 높기 때문이다.


## 404 페이지


존재하지 않는 경로에 접속할 때 표시되는 404 페이지를 커스터마이징할 수 있다. `pages` 폴더 최상위에 `404.tsx` 파일을 만들면 된다.


```typescript
// pages/404.tsx
import Link from 'next/link';

export default function Custom404() {
  return (
    <div>
      <h1>404 - 페이지를 찾을 수 없습니다</h1>
      <p>요청하신 페이지가 존재하지 않습니다.</p>
      <Link href="/">홈으로 돌아가기</Link>
    </div>
  );
}
```


빌드 시 자동으로 정적 페이지로 생성되므로 추가 서버 부하 없이 빠르게 제공된다.


## 참고 자료

- [Next.js 공식 문서 - Pages Router Routing](https://nextjs.org/docs/pages/building-your-application/routing)
- [Next.js 공식 문서 - next/link](https://nextjs.org/docs/pages/api-reference/components/link)
- [Next.js 공식 문서 - useRouter](https://nextjs.org/docs/pages/api-reference/functions/use-router)


Next.js

2025