# headers 함수 알아보기

`headers` 함수는 Server Component 내에서 HTTP 요청 헤더를 비동기로 읽을 수 있게 도와주는 유틸리티입니다. 간단히 말해, 클라이언트가 서버에 보낸 요청의 헤더 정보를 서버 컴포넌트 안에서 쉽게 확인할 수 있다는 거죠.

아래 예제를 보고 한번 살펴볼게요!

```js
import { headers } from 'next/headers'

export default async function Page() {
  const headersList = await headers()
  const userAgent = headersList.get('user-agent')

  return (
    <div>
      <p>당신의 User-Agent: {userAgent}</p>
    </div>
  )
}
```

- 여기서 `headers()`를 호출하면 요청에 포함된 모든 헤더 정보를 담은 객체를 비동기로 가져옵니다.
- `headersList.get('user-agent')`로 특정 헤더(`user-agent`) 값을 얻을 수 있어요.
- 이렇게 얻은 헤더 정보로 클라이언트 환경에 따라 다른 내용을 렌더링하거나, API 요청 시 헤더를 조작할 수도 있습니다.

> 참고로, `headers()` 함수는 Server Component에서만 사용 가능하기 때문에 클라이언트 컴포넌트에서는 사용할 수 없다는 점 기억하세요!

---

### 헤더 정보 활용 팁

- **사용자 환경 감지:** User-Agent 헤더를 통해 브라우저 종류나 버전을 확인할 수 있어, 맞춤형 UI를 제공할 때 유용해요.
- **보안 검사:** 특정 헤더 값을 검사해서 요청이 정상적인지 체크할 수도 있고, 토큰이나 인증 정보를 확인하는 데도 쓰입니다.
- **로깅 및 분석:** 클라이언트 IP, 언어 설정, 쿠키 등 다양한 헤더 정보를 기록해서 서비스 개선에 활용하세요.

---

필요할 때마다 `headers`를 활용하면 서버 사이드에서 더 스마트하게 사용자 요청을 다룰 수 있으니 꼭 기억해두세요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

### 파라미터

headers는 별도의 파라미터를 받지 않습니다.

### 반환값

headers는 읽기 전용(Web Headers) 객체를 반환합니다.

---

여기서 Web Headers 객체란, 웹 요청과 응답에 포함되는 헤더 정보를 나타내는 객체예요. 쉽게 말해서, 서버나 클라이언트가 주고받는 부가 정보를 가지고 있는 거죠. 주로 콘텐츠 타입(Content-Type), 인증 정보(Authorization), 캐시 제어(Cache-Control) 등 다양한 정보를 담고 있답니다.

이 객체가 읽기 전용이라서, 값들을 마음대로 바꾸지는 못하지만, 필요한 경우 새로운 헤더를 만들어서 요청에 추가할 수 있어요. 혹시 헤더를 조작하거나 확인하는 작업이 필요하다면, 이 점 참고하면 좋을 것 같아요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

Headers 객체 메서드 정리해봤어요! 웹 개발할 때 Headers 다룰 일 많으니 참고해 보세요.

| 메서드              | 설명                                                                                           |
|---------------------|------------------------------------------------------------------------------------------------|
| Headers.entries()   | Headers 객체에 들어있는 모든 키/값 쌍을 돌면서 이터레이터(iterator)를 반환해요.                      |
| Headers.forEach()   | Headers 내 각 키/값 쌍에 대해 한 번씩 제공한 함수를 실행해요.                                    |
| Headers.get()       | 특정 이름을 가진 헤더의 모든 값을 문자열(String)로 반환해요.                                    |
| Headers.has()       | 해당 헤더가 존재하는지 여부를 boolean으로 알려줘요.                                              |
| Headers.keys()      | 모든 키를 순회할 수 있는 이터레이터를 반환해요.                                                 |
| Headers.values()    | 모든 값을 순회할 수 있는 이터레이터를 반환해요.                                                 |

---

## 알아두면 좋은 점

- `headers` 함수는 비동기(async) 함수라 Promise를 반환해요. 그래서 `async/await` 문법이나 React에서 제공하는 hook들을 사용해야 합니다.

- Next.js 14버전 이전까진 `headers`가 동기 함수였는데, Next.js 15버전에서도 아직 동기 방식으로 접근은 가능하지만 점점 사라질 예정이에요. 호환성 때문에 아직 남겨두고 있긴 합니다.

- `headers`는 읽기 전용(Read-only)입니다. 그래서 요청 헤더를 새로 설정하거나 삭제하는 건 불가능해요.

- `headers`가 동적으로 API 값을 반환하기 때문에, 해당 라우트(페이지)는 자동으로 ‘동적 렌더링’ 모드로 들어갑니다. 정적 생성(Static Generation)이 필요한 상황에서는 주의하세요.

---

혹시 `Headers` 객체를 사용할 때 어떻게 데이터를 순회하는지 궁금하다면, 다음처럼 간단한 예제도 있어요!

```js
const headers = new Headers();
headers.append('Content-Type', 'application/json');
headers.append('X-Custom-Header', 'Value123');

for (const [key, value] of headers.entries()) {
  console.log(`${key}: ${value}`);
}

headers.forEach((value, key) => {
  console.log(`${key} = ${value}`);
});
```

이런 식으로 `entries()`로 반복문 사용하거나 `forEach`를 바로 쓸 수 있어요.

개발하시면서 Headers 객체를 다룰 일이 많다면, 이런 기본 메서드들을 익혀두면 훨씬 편리합니다. 꼭 기억해두세요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

### Authorization 헤더 사용하기

```js
import { headers } from 'next/headers'
 
export default async function Page() {
  const authorization = (await headers()).get('authorization')
  const res = await fetch('...', {
    headers: { authorization }, // Authorization 헤더 전달하기
  })
  const user = await res.json()
 
  return <h1>{user.name}</h1>
}
```

여기서 중요한 점은, Next.js 13부터 `headers()` 함수가 비동기 함수가 되었다는 거예요. 그래서 `await headers()`로 호출해야 하고, 그 결과에서 `authorization` 헤더 값을 가져올 수 있습니다. 그리고 이 값을 fetch 요청의 헤더로 그대로 넘겨줘서, 서버 간 인증 정보를 전달할 수 있죠.

이 방법은 특히 API 라우트나 서버 컴포넌트에서 클라이언트가 보낸 헤더를 그대로 백엔드 API에 넘길 때 유용해요. 예를 들어, JWT 토큰을 포함한 Authorization 헤더를 안전하게 전달할 수 있다는 뜻이죠.

다만, Authorization 헤더에는 민감한 정보가 많이 담기므로, 꼭 신뢰할 수 있는 환경에서만 이렇게 포워딩하고, 노출되지 않도록 주의해야 합니다.

---

## 버전 히스토리

| Version         | Changes                                                                                      |
|-----------------|----------------------------------------------------------------------------------------------|
| `v15.0.0-RC`    | `headers`가 이제 비동기 함수가 되었습니다. 관련 코드 변경을 도와주는 <a href="/docs/app/guides/upgrading/codemods#150">codemod</a>가 제공됩니다. |
| `v13.0.0`       | `headers` 함수가 도입되었습니다.                                                              |

---

참고로, 예전 Next.js 버전에서는 `headers`가 동기 함수였는데, 비동기 함수로 변경되면서 더 유연한 비동기 작업이 가능해졌어요. 업그레이드할 때는 이 점 꼭 체크하세요! 그리고 `authorization` 외에도 필요한 다른 헤더들도 동일한 방식으로 가져와서 활용할 수 있답니다.

Next.js 15에서 HTTP 요청 헤더 쉽게 작성하기 (headers) 

Next.js 15에서 generateViewport 함수로 반응형 페이지 만드는 방법

Next.js 13에서 generateStaticParams 사용법 정리

# generateSitemaps 함수 소개

웹사이트를 운영하다 보면, 검색엔진 최적화(SEO)를 위해 여러 개의 사이트맵(sitemap)을 만들어야 할 때가 있는데요. 이때 `generateSitemaps` 함수를 사용하면 여러 개의 사이트맵을 손쉽게 생성할 수 있어요.

## 반환값(Returns)

`generateSitemaps` 함수는 사이트맵을 여러 개 만들고, 각 사이트맵에 대해 `id`라는 프로퍼티를 가진 객체들의 배열을 반환합니다. 쉽게 말해, 생성된 사이트맵들의 고유 식별자 리스트를 받아볼 수 있다는 뜻이죠.

| 반환 유형   | 설명                                |
| --------- | --------------------------------- |
| 배열(Array) | 각각의 사이트맵을 나타내는 객체들로 구성됨 |
| 객체(Object) | 각 객체는 `id` 프로퍼티를 포함          |

---

### 추가 팁!

- 사이트맵을 여러 개로 나누는 것은 대규모 웹사이트에서 자주 쓰이는 전략입니다. 구글 같은 검색엔진은 한 사이트맵 파일에 너무 많은 URL이 들어가면 효율적으로 크롤링하지 못하거든요.
- `id` 값을 활용해서 나중에 각 사이트맵을 동적으로 불러오거나 관리할 때 용이합니다.
- 만약 사이트맵을 자동 생성할 수 있는 라이브러리나 툴을 사용 중이라면, 이 같은 함수는 내부적으로 페이지 URL들을 분배하고 각 파일을 생성하는 역할을 담당합니다.

웹사이트 규모가 커질수록 사이트맵 관리가 쉽지 않은데, 이런 함수를 잘 활용하면 관리도 편하고 SEO에도 훨씬 도움이 되니 꼭 참고하세요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

## URL 경로

생성된 사이트맵은 `/.../sitemap/[id].xml` 경로에서 확인할 수 있어요. 예를 들어, `/product/sitemap/1.xml` 같은 식이죠.

## 예시

사이트맵을 나누고 싶다면 `generateSitemaps` 함수에서 사이트맵 ID를 포함한 객체 배열을 반환하면 돼요. 그리고 이 ID를 활용해서 각각 고유한 사이트맵을 생성할 수 있답니다.

아래 표를 보면 좀 더 이해하기 편할 거예요.

| Sitemap ID | 생성되는 사이트맵 파일 경로    |
|------------|------------------------------|
| 1          | /product/sitemap/1.xml        |
| 2          | /product/sitemap/2.xml        |
| 3          | /product/sitemap/3.xml        |

이렇게 ID를 기준으로 사이트맵을 나누면, 대형 웹사이트에서도 효율적으로 검색 엔진에 페이지를 노출시킬 수 있어요. 대략 한 사이트맵에 50,000개 정도의 URL까지만 포함하는 게 권장되니까요.

만약 사이트맵이 너무 커서 관리가 힘들다면, 이렇게 ID를 쪼개서 여러 개로 만드는 방법을 꼭 활용해 보세요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

이 코드는 Next.js에서 동적 사이트맵을 생성하는 간단한 예제예요. 사이트맵은 검색 엔진이 내 사이트를 효율적으로 크롤링할 수 있도록 도와주는 중요한 역할을 하죠. 여기선 제품 목록(product)을 50,000개씩 나눠서 각각의 사이트맵을 만들어주는 구조예요.

```js
import { BASE_URL } from '@/app/lib/constants'
 
export async function generateSitemaps() {
  // 전체 상품 수를 불러와서 사이트맵 페이지 개수를 계산하는 대신, 임시로 4개의 사이트맵 페이지를 반환
  return [{ id: 0 }, { id: 1 }, { id: 2 }, { id: 3 }]
}
 
export default async function sitemap({
  id,
}: {
  id: number
}): Promise<MetadataRoute.Sitemap> {
  // 구글은 사이트맵에 최대 50,000개의 URL만 허용하니 이걸 기준으로 상품을 나눠서 가져옴
  const start = id * 50000
  const end = start + 50000
  const products = await getProducts(
    `SELECT id, date FROM products WHERE id BETWEEN ${start} AND ${end}`
  )
  return products.map((product) => ({
    url: `${BASE_URL}/product/${product.id}`,
    lastModified: product.date,
  }))
}
```

### 중요한 포인트
- 사이트맵을 너무 크게 만들면 구글에서 인식하기 어려우니 50,000개씩 분할하는 게 기본입니다.
- `generateSitemaps` 함수는 사이트맵의 페이지 목록을 반환하는 역할을 하고, 실제 각 페이지에 어떤 URL이 들어갈지 `sitemap` 함수에서 처리하죠.
- 실제 환경에서는 상품 총 개수를 DB에서 조회해 그에 맞게 페이지 수를 동적으로 만들어줘야 해요.

---

## 버전 히스토리

| 버전 | 변경사항 |
|-------|---------|
| `v15.0.0` | `generateSitemaps` 함수가 개발 환경과 프로덕션 환경에서 일관된 URL을 생성하도록 개선됨 |
| `v13.3.2` | `generateSitemaps` 함수 도입. 개발 시 `/.../sitemap.xml/[id]` URL을 통해 동적으로 생성된 사이트맵 확인 가능 (예: `/product/sitemap.xml/1`) |

---

### 추가 팁
- 사이트맵 URL을 서비스 루트에 쉽게 추가하고 싶다면, Next.js 내의 API Route를 사용하거나 서버리스 함수(Serverless Function)를 활용할 수도 있어요.
- 사이트맵 생성 시 추천하는 방법 중 하나는 정기적으로 크론 잡으로 상품 리스트 업데이트에 맞춰 사이트맵을 재생성하는 거예요.
- 큰 사이트라면 사이트맵 인덱스 파일을 만들어서 여러 개의 사이트맵 파일을 참조하는 전략도 있어요.

사이트맵은 SEO 최적화에도 굉장히 중요하니, 꼭 내 사이트 규모에 맞게 적절한 구조로 관리해 보세요!

Next.js 15에서 generateSitemaps 기능 쉽게 구현하는 2025년 최신 가이드

Next.js 15에서 generateMetadata 함수로 SEO 메타데이터 자동 생성하는 방법

# generateImageMetadata 함수 소개

여러분, 이미지 메타데이터를 다룰 때 직접 하나하나 값을 하드코딩하기 귀찮거나, 여러 버전의 이미지를 한꺼번에 처리하고 싶었던 적 있으신가요? 바로 그럴 때 `generateImageMetadata` 함수를 활용하면 정말 편리해요!

이 함수는 하나의 이미지를 다양한 버전으로 만들어내거나, 한 라우트 세그먼트에 여러 이미지를 반환할 수 있도록 도와줘요. 특히 아이콘 같이 자주 쓰이면서도 크기나 형식이 달라지는 이미지 작업에 아주 유용하답니다.

## 파라미터 (Parameters)

`generateImageMetadata` 함수에 넘겨줄 수 있는 주요 파라미터들은 아래와 같아요:

| 파라미터 이름 | 설명 |
| --- | --- |
| `src` | 기본 이미지 경로 또는 URL (필수) |
| `sizes` | 생성할 이미지 크기 배열 (예: `[16, 32, 64]`) |
| `formats` | 생성할 이미지 형식 배열 (예: `['png', 'webp']`) |
| `outputDir` | 변환 이미지가 저장될 디렉터리 경로 |
| `quality` | 이미지 압축 품질 (0~100) |
| `background` | 배경색 설정 (특히 투명하지 않은 이미지에 유용) |

위 내용은 가장 기본적이고 자주 사용하는 옵션들을 포함하고 있어요. 이외에도 상황에 따라 추가 설정이 가능하니 공식 문서를 참고하면 더 깊이 이해할 수 있습니다.

---

### 실무에서 이렇게 활용해보세요!

1. **아이콘 다양화**  
   앱이나 웹사이트 내에서 동일한 아이콘을 크기별, 포맷별로 자동 생성해서 사용하면 코드가 더 깔끔해지고, 다양한 기기 대응이 쉬워져요.

2. **SEO와 성능 최적화**  
   다양한 해상도와 포맷(WebP 등)을 지원하면 사용자의 네트워크 환경이나 브라우저에 맞춰 최적화된 이미지를 제공할 수 있어, 페이지 로딩 속도와 SEO에 도움이 됩니다.

다음번에는 이 함수를 실제 코드 예제와 함께 '어떻게 사용하는지' 자세히 다뤄볼게요! 질문이나 궁금한 점 있으면 언제든 댓글 남겨주세요 :)


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

#### params (선택 사항)

`params`는 동적 라우트 매개변수를 포함하는 객체인데요, 이 객체는 루트 세그먼트에서부터 `generateImageMetadata` 함수가 호출된 세그먼트까지의 매개변수를 담고 있어요.

예를 들어, 아래처럼 `generateImageMetadata` 함수에 `params`를 전달받을 수 있습니다.

```js
export function generateImageMetadata({
  params,
}: {
  params: { slug: string }
}) {
  // ...
}
```

이때, 라우트와 URL, 그리고 `params`의 예시는 다음 표처럼 이해하시면 편해요.

| Route                       | URL        | params              |
|-----------------------------|------------|---------------------|
| `app/shop/icon.js`           | `/shop`    | `undefined`         |
| `app/shop/[slug]/icon.js`    | `/shop/1`  | `{ slug: '1' }`     |
| `app/shop/[tag]/[item]/icon.js` | `/shop/1/2` | `{ tag: '1', item: '2' }` |

즉, URL 경로에 따라 `params` 객체 안에 전달되는 키와 값이 달라지는 거죠.

참고로, Next.js 같은 프레임워크에서는 이 `params`를 통해 동적으로 페이지를 구성할 때 유용하게 쓰여요. 특히 여러 단계의 동적 세그먼트가 있을 경우, 이 객체를 활용해 필요한 데이터를 가져오거나 메타데이터를 생성할 수 있답니다.

또 한 가지 팁을 드리자면, `params`가 `undefined`인 경우도 있으니 함수 내에서 안전하게 처리해주는 게 좋아요! 예를 들면 다음과 같이요:

```js
export function generateImageMetadata({ params }) {
  const slug = params?.slug ?? 'default';
  // slug를 안전하게 사용
}
```

이렇게 하면 예상치 못한 에러를 방지할 수 있답니다!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

## 리턴값 설명

`generateImageMetadata` 함수는 이미지 메타데이터를 담은 객체들의 배열을 반환해야 합니다. 여기서 각 객체는 이미지의 대체 텍스트(`alt`), 크기(`size`) 같은 정보를 포함하고 있어요. 그리고 꼭 포함해야 할 값 중 하나가 `id`인데, 이 값은 이미지 생성 컴포넌트에서 props로 전달받게 됩니다.

아래는 반환하는 객체 구조를 간단히 정리한 표예요:

| Image Metadata Object | Type                      |
|----------------------|---------------------------|
| `id`                 | `string` (필수)            |
| `alt`                | `string`                   |
| `size`               | `{ width: number; height: number }` |
| `contentType`        | `string`                   |

### 예제 코드

```js
import { ImageResponse } from 'next/og'
 
export function generateImageMetadata() {
  return [
    {
      contentType: 'image/png',
      size: { width: 48, height: 48 },
      id: 'small',
    },
    {
      contentType: 'image/png',
      size: { width: 72, height: 72 },
      id: 'medium',
    },
  ]
}
 
export default function Icon({ id }: { id: string }) {
  return new ImageResponse(
    (
      <div
        style={{
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          fontSize: 88,
          background: '#000',
          color: '#fafafa',
        }}
      >
        Icon {id}
      </div>
    )
  )
}
```

---

### 조금 더 설명을 덧붙이자면

- `generateImageMetadata` 함수는 이미지가 다양할 때 각각에 맞는 메타정보를 한꺼번에 관리할 수 있어 편리합니다.
- 각 이미지별 `id`는 컴포넌트에서 어떤 이미지를 렌더할지 구분하는 역할을 해요. 이 `id`를 이용해 동적으로 이미지 내용을 바꾸거나 다르게 스타일링할 수 있습니다.
- `contentType`은 보통 이미지 포맷을 지정하는데, 예를 들어 `image/png`나 `image/jpeg` 등을 쓸 수 있어요.
- `alt` 값은 UI 접근성을 높이기 위해 넣으면 좋습니다. 이미지 로딩 실패 시나 스크린 리더 사용자의 이해를 도와주니까요.

그리고 스타일링 부분에서, 인라인 스타일에 중괄호 `{}`를 빼먹을 수 있는데 꼭 유의하세요! 예제 코드처럼 객체형태로 잘 감싸야 합니다.

필요에 따라 더 다양한 메타데이터를 포함시켜 유연하게 확장하는 것도 추천드려요~!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

### 예제

#### 외부 데이터를 활용한 이미지 생성

이번 예제에서는 `params` 객체와 외부 데이터를 사용해 라우트 세그먼트에 대해 여러 개의 Open Graph 이미지를 생성하는 방법을 보여드릴게요.

```js
import { ImageResponse } from 'next/og'
import { getCaptionForImage, getOGImages } from '@/app/utils/images'

export async function generateImageMetadata({
  params,
}: {
  params: { id: string }
}) {
  const images = await getOGImages(params.id)

  return images.map((image, idx) => ({
    id: idx,
    size: { width: 1200, height: 600 },
    alt: image.text,
    contentType: 'image/png',
  }))
}

export default async function Image({
  params,
  id,
}: {
  params: { id: string }
  id: number
}) {
  const productId = (await params).id
  const imageId = id
  const text = await getCaptionForImage(productId, imageId)

  return new ImageResponse(
    (
      <div
        style={
          {
            // ...
          }
        }
      >
        {text}
      </div>
    )
  )
}
```

---

위 예제는 `params.id`를 기반으로 여러 Open Graph 이미지를 생성해주는 방식이에요. 먼저 `generateImageMetadata` 함수에서 외부 유틸 함수 `getOGImages`를 호출해 이미지 메타데이터들을 불러옵니다. 그리고 각각의 이미지를 원하는 크기와 alt 텍스트, 콘텐츠 타입과 함께 반환하죠.

또한, 이미지 생성 함수 `Image`에서는 각각의 이미지 ID와 제품 ID를 받아서 해당 이미지에 들어갈 텍스트 캡션을 외부에서 가져와 렌더링합니다.

> 참고로 이런 방식을 사용하면 한 가지 라우트에 여러 OG 이미지를 동적으로 생성할 수 있어서, SNS에서 링크를 공유할 때 다양한 시각적 표현이 가능해집니다.  
>  
> 그리고 `ImageResponse`는 Next.js의 `next/og` 모듈에서 제공하는 기능으로, JSX를 기반으로 이미지를 그릴 수 있게 해줘요. 평소 HTML이나 React를 다루는 것처럼 편하게 이미지 레이아웃도 조절 가능하니 참 편리합니다.

여기에 좀 더 스타일을 입히거나, 이미지 안에 다른 컴포넌트나 아이콘, 배경색 등을 넣어서 더욱 멋진 OG 이미지를 만들 수도 있겠네요. 이렇게 동적으로 메타데이터와 이미지를 생성하는 것은 SEO뿐만 아니라, 사용자 경험 향상에도 크게 도움을 줄 수 있습니다!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

## 버전 히스토리

| 버전      | 변경 사항                       |
|-----------|-------------------------------|
| v13.3.0   | `generateImageMetadata` 기능 추가 |

여기서 `generateImageMetadata`라는 기능이 새롭게 도입된 걸 확인할 수 있어요. 혹시 이미지 처리나 메타데이터 자동 생성과 관련된 작업을 한다면, 이 기능이 꽤 유용할 거예요. 나중에 직접 사용해보고 어떤 점이 좋은지, 어떻게 활용할 수 있는지도 다뤄볼게요!

Next.js 15에서 generateImageMetadata 함수 사용하는 방법

# forbidden 함수 사용법과 설정 가이드

안녕하세요! 오늘은 Next.js에서 권한 오류를 처리할 때 아주 유용한 `forbidden` 함수에 대해 알아볼게요. 이 함수는 권한이 없을 때 403 에러 페이지를 띄워주는데, 기본 제공 UI를 `forbidden.js` 파일로 직접 커스터마이징할 수도 있어서 유용하답니다.

## forbidden 함수란?

`forbidden` 함수는 사용자가 접근 권한이 없을 때 호출하면, Next.js가 자동으로 403 에러 페이지를 렌더링해 줍니다. 보통 로그인 상태나 권한 상태를 체크할 때 유용하게 쓸 수 있어요.

## 설정 방법

`forbidden` 함수를 쓰려면 먼저 `next.config.js`에서 실험적 기능인 `authInterrupts` 옵션을 활성화해야 합니다. 아래처럼 설정해 주세요:

```js
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    authInterrupts: true,
  },
}

export default nextConfig
```

이 설정을 하면 `forbidden` 함수를 호출했을 때 Next.js가 자동으로 권한 부족 화면을 보여주게 됩니다.

## forbidden.js로 UI 커스터마이징하기

기본 403 화면 대신 회사나 프로젝트에 맞는 디자인으로 꾸미고 싶다면, 앱 루트에 `forbidden.js` 파일을 만들어서 커스텀 UI를 구현할 수 있어요.

예를 들어:

```jsx
export default function Forbidden() {
  return (
    <div style={{ textAlign: 'center', padding: '2rem' }}>
      <h1>403 - 접근 금지</h1>
      <p>죄송합니다만, 이 페이지에 접근할 권한이 없습니다.</p>
      <button onClick={() => window.location.href = '/login'}>
        로그인 페이지로 가기
      </button>
    </div>
  )
}
```

이런 식으로 친근한 UI를 만들어 놓으면 사용자 경험이 더 좋아질 거예요.

## 팁: 권한 체크 로직과 연동하기

실제로는 서버나 클라이언트에서 인증 정보를 확인한 후, 권한이 없으면 `forbidden()`을 호출하는 식으로 동작합니다. 예를 들어:

```js
import { forbidden } from 'next/dist/server/api-utils'

export async function getServerSideProps(context) {
  const user = await getUserFromSession(context.req)

  if (!user || !user.hasAccess) {
    throw forbidden()
  }

  return { props: { user } }
}
```

이렇게 하면 권한이 없는 사용자에겐 자동으로 403 페이지가 렌더링됩니다.

---

Next.js에서 권한 관련 에러 처리를 깔끔히 하고 싶다면 `forbidden` 함수와 `authInterrupts` 설정을 적극 활용해 보세요. 기본 UI는 귀찮으면 그대로 써도 좋고, 필요하면 `forbidden.js`로 멋지게 꾸며 보시고요!

필요한 내용 있으면 언제든 질문 남겨 주세요~ :)


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

next.js에서 `forbidden` 함수는 Server Components, Server Actions, 그리고 Route Handlers 안에서만 호출할 수 있어요. 이 함수는 권한이 없는 사용자가 특정 페이지에 접근하려 할 때 간단하게 403 상태 코드를 반환하도록 도와주는데요, 예를 들어 관리자 페이지 같은 경우에 유용하게 사용할 수 있죠.

아래 예시를 한번 보세요:

```jsx
import { verifySession } from '@/app/lib/dal'
import { forbidden } from 'next/navigation'
 
export default async function AdminPage() {
  const session = await verifySession()
 
  // 사용자가 'admin' 역할인지 확인
  if (session.role !== 'admin') {
    forbidden() // 권한 없으면 403 에러를 발생시켜요.
  }
 
  // 권한이 있으면 관리자 페이지 렌더링
  return <></>
}
```

여기서 `verifySession()`은 사용자 세션을 확인하고, 세션에 포함된 `role` 정보를 바탕으로 권한 검사를 하게 됩니다. 만약 역할이 'admin'이 아니라면 `forbidden()` 함수를 호출해서 접근을 차단하는 거죠.

### 알고 있으면 좋은 점
- `forbidden` 함수는 루트 레이아웃(root layout)에서는 호출할 수 없어요. 루트 레이아웃에서 호출하면 에러가 발생하니 주의하세요.
- `forbidden()` 이 호출되면 HTTP 상태 코드 403이 자동으로 반환되고, 페이지는 더 이상 렌더링되지 않습니다.
- 이 방법은 클라이언트 사이드가 아닌 서버 사이드에서 권한 체크가 진행되기 때문에 보안적으로 훨씬 안전합니다.

요약하면, Next.js에서 권한 제어를 할 때 서버 컴포넌트나 서버 액션, 라우트 핸들러에서 `forbidden()`을 이용해 간편하고 안전하게 접근을 제한할 수 있다는 점 기억하세요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

## 예제

### 역할(role) 기반 라우트 보호

`forbidden` 함수를 사용하면 유저의 역할에 따라 특정 페이지 접근을 제한할 수 있어요. 인증은 되었지만 권한이 없는 사용자가 중요한 페이지에 들어오는 걸 막는 데 아주 유용하답니다.

```js
import { verifySession } from '@/app/lib/dal'
import { forbidden } from 'next/navigation'

export default async function AdminPage() {
  const session = await verifySession()

  // 유저의 역할이 'admin'인지 확인하기
  if (session.role !== 'admin') {
    forbidden()  // 권한 없으면 접근 금지 처리
  }

  // 권한이 확인된 사용자에게 관리자 페이지 렌더링
  return (
    <main>
      <h1>Admin Dashboard</h1>
      <p>Welcome, {session.user.name}!</p>
    </main>
  )
}
```

---

### 조금 더 설명을 덧붙이자면

- `verifySession()` 같은 함수는 보통 로그인 상태와 사용자 정보를 서버에서 확인하는 역할을 해요.
- `forbidden()`이 호출되면 Next.js가 자동으로 403 상태 코드를 반환하면서 페이지 렌더링을 막아요.
- 이 구조를 응용하면 관리자뿐만 아니라 일반 회원, VIP 등 다양한 권한 기반 페이지 구성이 깔끔하게 가능하답니다.
- 클라이언트 쪽이 아니라 서버 사이드에서 권한 검사를 하기에 보안도 한층 강해지죠.

이런 식으로 `forbidden()`을 적절히 써서 중요한 페이지에 사용자 권한을 확실히 적용할 수 있답니다!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

### Server Actions에서의 Mutation 사용하기

서버 액션(Server Actions)으로 뮤테이션(mutation)을 구현할 때, 민감한 데이터를 업데이트하는 작업은 꼭 특정 권한이 있는 사용자만 할 수 있도록 제한하는 게 중요해요. 예를 들어, 관리자(admin)만 역할(role)을 변경할 수 있게 막는 방법을 살펴볼게요.

```js
'use server'

import { verifySession } from '@/app/lib/dal'
import { forbidden } from 'next/navigation'
import db from '@/app/lib/db'

export async function updateRole(formData: FormData) {
  const session = await verifySession()

  // 관리자만 역할 변경 권한을 부여
  if (session.role !== 'admin') {
    forbidden()
  }

  // 권한 확인 후 역할 업데이트 로직 수행
  // ...
}
```

여기서 중요한 건 `verifySession()` 함수를 통해 현재 사용자의 세션 정보를 받아와서, 역할(role)이 'admin'인지 확인하는 부분이에요. 만약 관리자가 아니라면, `forbidden()` 함수를 호출해서 접근을 막아요. 이 함수는 Next.js의 내비게이션에서 권한을 제한할 때 쓰이는 함수로, 권한이 없으면 클라이언트에 적절한 에러 페이지를 보여줍니다.

---

### 덧붙여서!

- **세션 검증은 꼭 서버에서!**  
  세션이나 권한 체크 등 보안과 관련된 로직은 클라이언트가 아니라 서버에서 처리해야 안전합니다.

- **forbidden() 외 에러 처리**  
  상황에 따라서는 `forbidden()` 대신 직접 403 응답을 커스텀할 수도 있지만, Next.js 내장 함수 사용이 더 간편하고 안전하죠.

- **코드 구조 고민하기**  
  `updateRole` 같은 함수는 재사용성, 테스트 용이성 측면에서 최대한 작게, 명확하게 작성하는 게 좋아요.

- **db 연동**  
  주석 처리된 부분에는 실제 데이터베이스 업데이트 로직을 넣으면 되는데, 예를 들어 Prisma 같은 ORM을 사용한다면, `db.user.update()` 같은 함수를 호출해서 처리할 수 있어요.

서버 액션에서 뮤테이션을 처리할 때 권한 체크를 깔끔하게 하는 방법, 참고가 되었으면 좋겠습니다!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

아래는 위의 HTML table 태그를 Markdown 형식으로 바꾼 내용입니다.

| Version   | Changes                   |
|-----------|---------------------------|
| `v15.1.0` | `forbidden` introduced.   |

여기서 `forbidden`이라는 새 기능이 v15.1.0 버전에 추가됐다고 하는데요, 보통 이런 변화는 특정 상황에서 접근을 제한하거나 권한을 관리할 때 활용되곤 합니다. 만약 여러분이 API나 설정에서 권한 관련 처리를 한다면, `forbidden` 옵션이 어떤 역할을 하는지 한번 체크해보는 것도 좋겠네요!

Next.js 15에서 Forbidden 에러 해결하는 방법

# draftMode

이번에 소개할 기능은 Next.js에서 제공하는 `draftMode`라는 async 함수입니다. 이 함수는 서버 컴포넌트(Server Component) 내에서 Draft Mode를 켜고 끌 수 있게 해주고, 현재 Draft Mode가 활성화되어 있는지도 확인할 수 있어요.

```js
import { draftMode } from 'next/headers'

export default async function Page() {
  const { isEnabled } = await draftMode()
  // isEnabled가 true면 Draft Mode가 활성화된 상태,
  // false면 비활성화 상태입니다.
}
```

## Draft Mode란?

Next.js에서 Draft Mode는 관리자나 콘텐츠 작성자가 실제 공개된 페이지와는 별개로 콘텐츠를 미리보기하거나 테스트할 때 유용합니다. 보통 CMS(Content Management System)와 연동해서, 아직 퍼블리시되지 않은 글이나 변경사항을 미리 볼 때 많이 활용되죠.

## draftMode 함수 주요 기능

- **활성화**: Draft Mode 켜기
- **비활성화**: Draft Mode 끄기
- **상태확인**: 현재 Draft Mode가 켜져 있는지 확인

### 예를 들어 Draft Mode를 켜고 끄는 방법

아래처럼 `enable()`과 `disable()` 메서드를 쓸 수 있어요.

```js
import { draftMode } from 'next/headers'

export default async function Page() {
  const draft = await draftMode()

  // Draft Mode 활성화
  draft.enable()

  // Draft Mode 비활성화 (필요시)
  // draft.disable()

  const { isEnabled } = await draftMode()
  console.log('Draft Mode 활성화 여부:', isEnabled)
}
```

## 참고할 점

- `draftMode()`는 서버 컴포넌트에서만 쓸 수 있습니다. 클라이언트 컴포넌트에서는 동작하지 않아요.
- 주로 CMS와 함께 사용해, 콘텐츠 미리보기를 간단하게 구현할 때 유용합니다.
- Draft Mode가 켜져 있으면, 예를 들어 API 요청 시 비공개 상태인 콘텐츠도 가져오도록 설정할 수 있죠.

요즘 Next.js가 점점 서버 기능과 콘텐츠 관리 기능을 강화하는데, Draft Mode는 그 중에서도 굉장히 실용적인 기능이니 꼭 한번 써보시길 추천합니다!  

---

## Reference

- [Next.js Documentation - draftMode](https://nextjs.org/docs/app/building-your-application/configuration/draft-mode) (공식 문서 링크)


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

다음은 Draft Mode에서 사용할 수 있는 메서드와 프로퍼티들입니다:

| 메서드         | 설명                                                         |
| -------------- | ------------------------------------------------------------ |
| `isEnabled`    | Draft Mode가 활성화되어 있는지 여부를 나타내는 boolean 값입니다. |
| `enable()`     | Route Handler에서 Draft Mode를 활성화하며, 이때 `__prerender_bypass` 쿠키를 설정합니다. |
| `disable()`    | Route Handler에서 Draft Mode를 비활성화하며, 쿠키를 삭제합니다. |

---

## 알아두면 좋은 팁

- `draftMode` 함수는 비동기 함수로, Promise를 반환합니다. 따라서 `async/await`를 사용하거나 React의 `use` 함수를 사용해야 해요.  
  예전(Next.js 14버전 이하)에는 `draftMode`가 동기 함수였는데, 15버전에서는 하위 호환성을 위해 동기 접근도 가능하지만 곧 Deprecated될 예정입니다.

- `next build`를 할 때마다 새로운 우회 쿠키 값이 생성되기 때문에, 이 쿠키 값을 예측하기 어렵습니다. 보안 측면에서 좋은 변화죠!

- 로컬에서 Draft Mode를 HTTP로 테스트할 때는 브라우저 설정에서 **서드파티 쿠키 허용** 및 **로컬 스토리지 접근 허용**이 필요하니 참고하세요.

---

### 좀 더 자세한 설명!

`Draft Mode`는 쉽게 말해 "임시 저장" 모드 같은 개념인데요, 보통은 빌드된 정적 페이지를 보여주지만, 이 모드를 켜면 실시간으로 수정 중인 데이터를 확인할 수 있어 개발할 때 정말 유용합니다. 예를 들어, CMS에서 콘텐츠를 수정하며 바로바로 결과를 확인하고 싶을 때 많이 쓰이죠.

`enable()`을 호출하면 내부적으로 `__prerender_bypass`라는 쿠키가 설정되고, Next.js 서버는 이 쿠키를 보고 캐시된 정적 파일 대신 최신 서버 데이터를 반환합니다. 그리고 개발이 끝났으면 `disable()`을 호출해서 쿠키를 삭제해 다시 캐싱된 페이지를 보여주도록 해요.

마지막으로, 비동기 함수라는 점을 꼭 주의하세요. Next.js가 점점 비동기 패턴을 밀고 있기 때문에, 예전처럼 동기적으로 호출하면 버그가 날 수 있으니 async/await 사용을 권장합니다.

이 글이 Draft Mode를 이해하는 데 도움이 됐길 바라요! 개발하면서 궁금한 점 있으면 언제든 물어보세요~


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

## 예제

### Draft Mode 활성화하기

Draft Mode를 사용하려면 새로운 Route Handler를 만들고 `enable()` 메서드를 호출하면 돼요. 이렇게 하면 임시로 수정 중인 내용을 확인할 수 있답니다.

```js
import { draftMode } from 'next/headers'

export async function GET(request: Request) {
  const draft = await draftMode()
  draft.enable()
  return new Response('Draft mode is enabled')
}
```

---

### 조금 더 설명하자면?

`draftMode()` 함수는 현재 요청에서 Draft Mode의 상태를 제어할 수 있는 객체를 반환해줘요. 그 객체의 `enable()` 메서드를 호출하면 그 사용자의 세션에 Draft Mode가 활성화돼서, 보통은 비공개로 관리되는 수정 중인 콘텐츠들을 볼 수 있게 되죠.

예를 들어, 컨텐츠 수정 중인 페이지를 실시간으로 확인하고 싶을 때 엄청 편리해요. 반대로 `disable()` 메서드를 호출하면 Draft Mode가 해제됩니다.

Next.js를 사용 중이라면 이 기능을 활용해서 콘텐츠 검수나 개발 중인 기능 확인도 쉽게 할 수 있으니, 꼭 한 번 써보세요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

### Draft Mode 끄기

기본적으로 Draft Mode는 브라우저를 닫으면 세션이 종료돼요.

하지만 직접 Draft Mode를 끄고 싶다면, Route Handler 안에서 `disable()` 메서드를 사용하면 돼요. 예를 들어:

```js
import { draftMode } from 'next/headers'

export async function GET(request: Request) {
  const draft = await draftMode()
  draft.disable()
  return new Response('Draft mode is disabled')
}
```

이렇게 하면 현재 세션에서 Draft Mode가 비활성화돼서, 더 이상 임시 콘텐츠나 수정된 내용을 확인할 수 없게 돼요.

여기서 한 가지 팁! 보통 Draft Mode는 테스트나 미리보기용으로 많이 쓰이니, 실제 서비스에선 잘 꺼두는 게 좋아요. Draft Mode가 켜진 상태에서는 캐싱이나 일부 기능이 동작하지 않을 수 있으니까요.

참고로, Next.js의 `draftMode()`는 클라이언트-서버 환경 모두에서 사용 가능해, 서버에서 조건에 따라 쉽게 Draft Mode를 켜고 끌 수 있다는 점도 기억해두세요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

여러분, Next.js에서 Route Handler를 호출할 때 주의할 점이 있어요! 만약 `Link` 컴포넌트를 이용해서 라우트를 호출한다면, `prefetch='false'`를 꼭 넘겨줘야 해요. 이걸 안 하면 prefetch 과정에서 쿠키가 의도치않게 삭제될 수 있거든요. 

---

### Draft Mode가 켜져 있는지 확인하는 방법

서버 컴포넌트(Server Component)에서 Draft Mode가 활성화되어 있는지 확인하고 싶을 때는, `next/headers` 모듈의 `draftMode` 함수를 사용하면 돼요. 이 함수는 `isEnabled`라는 프로퍼티를 반환하는데, 이걸 통해 현재 Draft Mode 상태를 알 수 있죠.

아래 코드를 한 번 보세요:

```js
import { draftMode } from 'next/headers'

export default async function Page() {
  const { isEnabled } = await draftMode()
  return (
    <main>
      <h1>My Blog Post</h1>
      <p>Draft Mode is currently {isEnabled ? 'Enabled' : 'Disabled'}</p>
    </main>
  )
}
```

이렇게 하면 페이지를 렌더링할 때 Draft Mode가 켜져 있는지 바로 확인할 수 있어요. 

> 팁 하나 더! Draft Mode는 예를 들어 컨텐츠를 작성하거나 수정할 때 유용해요. 실제로 배포된 최종 버전에 반영되기 전에 미리 볼 수 있게 해주는 기능이라, 가끔 이 상태가 켜져 있는지 확인해 보는 것이 중요하답니다.


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

## 버전 히스토리

| 버전           | 변경사항                                                                                 |
| -------------- | ---------------------------------------------------------------------------------------- |
| `v15.0.0-RC`   | `draftMode`가 이제 비동기 함수(async function)로 변경되었습니다. 관련 [코드모드(codemod)](/docs/app/guides/upgrading/codemods#150)도 제공 중이에요. |
| `v13.4.0`      | `draftMode` 기능이 처음 도입되었습니다.                                                  |

---

여기서 잠깐! `draftMode`라는 기능이 뭔지 궁금하신 분들도 계실텐데요, 쉽게 말해서 Next.js에서 "초안 모드"처럼 작동해서 페이지가 캐시되지 않고 항상 최신 상태를 유지하도록 도와주는 기능이에요. 특히 서버사이드 렌더링하거나 ISR(Incremental Static Regeneration)을 사용할 때 실시간 업데이트가 필요할 때 유용하답니다.

그리고 `v15.0.0-RC`부터는 이 `draftMode` 함수가 async로 바뀌면서, 내부에서 비동기 작업이 가능해졌어요. 만약 이전 버전에서 사용 중이라면 코드 모드를 통해 자동으로 변환할 수 있으니 큰 걱정 하지 않아도 됩니다! 

Next.js 같은 프레임워크가 계속 발전하면서 이런 세세한 변경사항도 꼭 챙겨 두시는 게 좋아요. 개발할 때 버전별 차이로 헷갈리는 일이 줄어들 거예요!

Nextjs 15에서 draftMode 기능 사용하는 방법

# fetch

Next.js에서는 기본 웹 fetch() API를 확장해서, 서버에서 각 요청마다 고유한 지속 캐싱(persistent caching)과 재검증(revalidation) 규칙을 설정할 수 있도록 했어요.

브라우저에서는 fetch 요청 시 cache 옵션이 브라우저 HTTP 캐시와 어떻게 상호작용할지를 지정하잖아요? 그런데 Next.js의 확장된 fetch에서는 서버 사이드에서 할 때 이 cache 옵션이 프레임워크가 관리하는 지속 데이터 캐시(persistent Data Cache)와 어떻게 상호작용할지를 결정해줘요.

즉, 서버 컴포넌트 안에서 async/await와 함께 그냥 fetch를 호출해도, 이 캐시 전략들이 작동하면서 성능 향상 및 데이터 최신성을 관리해준다는 뜻이에요.

---

### 추가 설명

- **지속 데이터 캐시란?**  
  서버에서 한 번 가져온 데이터를 일정 시간 동안 저장해서, 같은 데이터를 재요청할 때 네트워크 호출을 줄여주는 역할을 해요. 그래서 유저 입장에선 페이지가 더 빨리 로드되고, 서버 부담도 줄어들죠.

- **재검증(revalidation)이 뭐예요?**  
  캐시된 데이터가 오래되었는지 주기적으로 체크해서, 최신 데이터가 필요하면 다시 fetch를 하는 거예요.

- **서버 컴포넌트에서 fetch를 쓴다?**  
  Next.js 13부터 도입된 서버 컴포넌트 덕분에, 서버에서 비동기적으로 데이터를 패칭하고 바로 렌더링할 수 있어요. 클라이언트에서 데이터 로딩 처리하는 걸 줄일 수 있죠.

---

### 예시 코드

```jsx
// 서버 컴포넌트 내에서 fetch 사용
export default async function Page() {
  const res = await fetch('https://api.example.com/data', {
    cache: 'force-cache'  // 고정된 캐시 전략 적용
  });
  const data = await res.json();

  return (
    <div>
      <h1>서버에서 가져온 데이터</h1>
      <pre>{JSON.stringify(data, null, 2)}</pre>
    </div>
  )
}
```

Next.js의 fetch API 확장 덕분에 서버 쪽 데이터 요청을 더 똑똑하게 관리할 수 있으니, 다음 프로젝트에 꼭 활용해보세요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

여러분, Next.js에서 데이터를 불러오는 방법에 대해 이야기해볼게요. 위에 있는 코드를 보시면, `fetch` 함수로 외부 API에서 데이터를 받아와서 화면에 포스트 리스트를 렌더링하는 아주 기본적인 예제입니다.

```jsx
export default async function Page() {
  let data = await fetch('https://api.vercel.app/blog')
  let posts = await data.json()
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}
```

### Next.js의 fetch() API 활용

Next.js는 기본적으로 웹의 `fetch()` API를 확장해서 제공하는데요, 그래서 우리가 익숙한 `fetch` 옵션들을 그대로 사용할 수 있다는 점이 편리해요. 이번에 살펴볼 옵션 중 하나가 `cache` 옵션입니다.

### `options.cache`

`cache` 옵션은 데이터를 어떻게 캐싱할지를 결정하는 역할을 해요. 예를 들어, 기본적으로는 서버 컴포넌트에서 데이터를 패칭할 때 `cache`가 적용되어, 다음에 같은 요청이 오면 캐시된 데이터를 바로 사용할 수 있도록 돼 있죠. 이걸 조절하면, 실시간 데이터가 중요하거나, 너무 자주 데이터를 갱신할 필요가 있을 때 유용해요.

- `"default"`: 기본 캐싱 정책을 따릅니다.
- `"no-cache"`: 매번 네트워크에서 새 데이터를 받아옵니다.
- `"force-cache"`: 캐시된 데이터만 사용하고 네트워크 요청은 안 합니다.
- `"only-if-cached"`: 캐시된 데이터가 없으면 실패합니다.

예를 들어, 이렇게 쓸 수 있어요:

```js
let data = await fetch('https://api.vercel.app/blog', { cache: 'no-cache' })
```

이렇게 하면 무조건 최신 데이터를 받아오기 때문에, 실시간 뉴스나 가격 정보처럼 자주 업데이트되는 데이터에 적합합니다.

---

### 한 가지 꿀팁!

Next.js 13부터는 `fetch`에 `next` 옵션도 함께 쓸 수 있는데요, 굉장히 강력합니다. 예를 들어 `next: { revalidate: 10 }` 옵션을 넣으면, 데이터를 받아와서 10초마다 캐시를 리프레시하도록 할 수 있어요. 이렇게 하면 서버 부하도 줄이고, 사용자는 어느 정도 최신 데이터를 볼 수 있죠.

```js
let data = await fetch('https://api.vercel.app/blog', {
  next: { revalidate: 10 }
})
```

한마디로, 여러분 프로젝트 상황에 맞게 캐시 전략을 유연하게 조절해 보세요. 그럼 데이터 패칭도 똑똑하게 할 수 있답니다!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

Next.js에서 요청이 데이터 캐시와 어떻게 상호작용할지 설정하는 방법에 대해 설명해드릴게요.

```js
fetch(`https://...`, { cache: 'force-cache' | 'no-store' })
```

여기서 cache 옵션은 세 가지 주요 상태가 있어요:

| 옵션          | 동작 설명                                                                                           |
|---------------|---------------------------------------------------------------------------------------------------|
| auto (기본값) | 개발 환경에서는 매 요청마다 원격 서버에서 데이터를 가져와요. 하지만 빌드 시점에 페이지가 정적으로 사전 렌더링되면 그때 한 번만 가져와요. 그리고 동적 API가 감지되면 매 요청마다 데이터를 가져오죠. |
| no-store      | 동적 API 여부와 상관없이 항상 매 요청마다 원격 서버에서 데이터를 가져와요. 캐시를 사용하지 않는 느낌이에요.                    |
| force-cache   | Next.js의 데이터 캐시에서 일치하는 요청이 있는지 찾아요. ‘신선한’ 캐시가 있으면 캐시에서 바로 반환하고, 없거나 오래된 캐시라면 원격 서버에서 새로 데이터를 받아와 캐시를 업데이트해요.  |

### 추가 꿀팁!

- 캐시가 ‘신선한(fresh)’하다는 말은 캐시된 데이터가 아직 유효하다는 뜻이에요. 이를 판단하는 기준은 Next.js 내부 정책이나 `revalidate` 옵션에 따라 달라집니다.
- `force-cache`를 사용하면 빌드 시점의 데이터를 최대한 활용하면서도, 변경사항이 있을 때만 서버에서 최신 데이터를 받을 수 있어서 효율적이에요.
- 개발 중에는 기본 `auto` 모드가 편리하지만, 프로덕션 환경에서는 상황에 맞게 `no-store` (실시간 업데이트 필요 시)나 `force-cache` (최소한의 요청으로 성능 최적화 시)를 선택하는 게 좋아요.

### options.next.revalidate

이 옵션은 캐시를 갱신하는 주기를 설정할 때 쓰입니다. 예를 들어, 

```js
fetch('https://...', { next: { revalidate: 60 } })
```

이렇게 설정하면, 캐시된 데이터가 60초가 지나면 다음 요청 때 새로 갱신해요. 다시 말해, 1분마다 데이터를 새로고침하는 것과 같죠.

이걸 적절히 활용하면 새로 고침의 빈도와 SEO 최적화를 균형 있게 맞출 수 있습니다.

---

Next.js의 데이터 캐시는 페이지 성능과 사용자 경험에 큰 영향을 주니, 개발 환경과 서비스 특성에 맞게 잘 설정해 보세요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

fetch 함수에 `next: { revalidate: ... }` 옵션을 주면 리소스의 캐시 수명을 초 단위로 설정할 수 있어요. 쉽게 말해, 캐시가 얼마 동안 유지될지 정하는 거죠. 이 옵션에 따라 캐싱 동작이 달라집니다.

| revalidate 값 | 의미                                                         |
|---------------|--------------------------------------------------------------|
| false         | 리소스를 무한정 캐시해요. (사실상 revalidate: Infinity와 같아요.) HTTP 캐시는 오랫동안 쓰다가 오래된 캐시를 지울 순 있지만, 기본적으로 무제한으로 저장합니다. |
| 0             | 캐시를 절대 하지 않아요. 항상 리소스를 새롭게 받아옵니다.       |
| number        | 숫자(초)만큼 캐시 생명주기를 정해요. 예를 들어 60이면 60초간 캐시 유지. |

### 좀 더 알아두면 좋은 점

- 특정 fetch 요청에서 설정한 `revalidate` 값이 라우트(route) 기본 값보다 작으면, 라우트 전체의 리밸리데이트 간격도 그만큼 줄어듭니다.
- 같은 URL을 가진 두 개의 fetch 요청이 각각 다른 `revalidate` 값을 가지고 있다면, 더 짧은 시간(낮은 값)이 적용됩니다.
- `revalidate`를 숫자로 주면 따로 `cache` 옵션을 설정하지 않아도 돼요.
- `revalidate`와 `cache` 옵션이 모순되는 설정(예: `revalidate: 3600`인데 `cache: 'no-store'`)을 하면 에러가 발생해요.

### 참고로,
이 옵션은 Next.js에서 제공하는 기능으로, 서버 측 데이터 패칭 시 자동으로 ISR(Incremental Static Regeneration)을 조절하는데 유용합니다. 개발할 때 캐시 정책을 유연하게 조절하면, 페이지 성능과 최신성 사이에서 좋은 균형을 맞출 수 있어요.

혹시 어떻게 쓰는지 구체적인 예시가 궁금하다면 알려주세요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

### options.next.tags

```js
fetch(`https://...`, { next: { tags: ['collection'] } })
```

`options.next.tags`는 요청에 캐시 태그(cache tags)를 설정하는 옵션이에요. 캐시 태그를 지정해두면, 나중에 `revalidateTag` API를 사용해서 해당 태그가 붙은 데이터만 선택적으로 갱신할 수 있답니다. 이렇게 하면 불필요하게 전체 데이터를 다시 받아오지 않아도 되니까 성능 최적화에 큰 도움이 되죠.

- **태그 길이 제한**: 각 태그는 최대 256자까지만 작성할 수 있어요.
- **태그 개수 제한**: 한 요청당 최대 128개의 태그를 설정할 수 있어요.

---

### 추가 팁!

`revalidateTag`를 사용하면 페이지나 일부 컴포넌트에서 특정 태그를 기반으로 데이터를 갱신할 수 있어서 리얼타임 데이터 반영이나, 변경이 잦은 부분만 업데이트할 때 매우 유용해요.

예를 들어, 쇼핑몰에서 ‘상품 컬렉션(collection)’ 태그를 붙인 데이터만 따로 갱신하고 싶을 때 편리하겠죠? 커스텀 태그를 잘 활용해서 앱 성능과 사용자 경험을 한층 개선해 보세요! 

---

## 문제 해결 (Troubleshooting)

| 문제 상황                        | 해결 방법                                 |
|-------------------------------|----------------------------------------|
| 태그가 너무 길 때               | 태그 길이를 256자 이내로 줄이세요.        |
| 태그 개수가 128개를 초과할 때   | 필요 없는 태그를 제거하거나 그룹화하세요. |
| 데이터가 갱신되지 않을 때       | `revalidateTag`가 올바르게 호출되었는지 확인하세요. |
| 캐시가 정상 동작하지 않을 때   | fetch 옵션과 캐시 정책을 다시 점검해보세요.   |

혹시 캐시 관련해서 더 궁금한 점이나, 특정 상황에서 어떻게 활용하면 좋은지 알고 싶다면 언제든 질문해 주세요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

### Fetch 기본 자동 no-store와 캐시: `no-store`가 개발 환경에서 최신 데이터를 보여주지 않는 이유

Next.js에서 개발할 때, 특히 **Server Components**를 사용할 때 조금 특이한 캐싱 동작이 있어요. 바로 HMR(Hot Module Replacement) 과정에서 fetch 응답을 캐시에 저장한다는 점입니다. 이 덕분에 빠른 응답 속도와 함께, API 호출 비용도 아낄 수 있죠.

그런데 여기서 중요한 점! HMR 캐시는 기본적으로 모든 fetch 요청에 적용되는데, 심지어 `cache: 'no-store'` 옵션을 넣어도 마찬가지라는 거예요. 즉, 기본값인 `no-cache`나 `cache: 'no-store'`를 사용해도 HMR 중에는 캐시가 유지되어서 **최신 데이터가 바로바로 안 보일 수 있습니다**. 

하지만 실제로 페이지를 새로고침하거나 다른 경로로 이동할 때는 캐시가 깨져서 다시 최신 데이터를 가져오게 돼요.

이게 개발할 때 가끔 데이터를 바로바로 바꿔서 테스트하는 과정에서 헷갈리게 할 수 있으니 주의해야 합니다.

추가로 궁금하다면 [serverComponentsHmrCache 문서](https://nextjs.org/docs/advanced-features/react-18/server-components#hot-module-replacement-cache)도 확인해보세요!

---

### 참고로 알아두면 좋은 점

- `cache: 'no-store'` 옵션은 **프로덕션 환경에선 실제로 캐시를 안 해서 무조건 최신 데이터를 가져오지만**,
- 개발 모드에서만 HMR 캐시가 이를 덮어씌웁니다.
- 이 때문에 개발 중에는 **fetch 요청이 예상과 다르게 동작할 수 있으니 주의**해야 해요.
- 만약 진짜 최신 데이터를 계속 보고 싶다면, [페이지를 새로고침하거나 다른 경로로 이동하는 방법](https://nextjs.org/docs/basic-features/data-fetching#refreshing-data-on-client-navigation)을 쓰는 게 좋습니다.

이런 Next.js 내부 동작 방식을 살펴보는 건 개발 생산성을 높이고, 예상치 못한 버그를 막는 데 큰 도움이 됩니다!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

## 버전 히스토리

| 버전       | 변경 사항           |
|------------|---------------------|
| `v13.0.0`  | `fetch` 기능 추가됨 |

여기서 `fetch`는 데이터를 서버에서 가져올 때 자주 사용하는 기능인데, 이 버전부터 공식적으로 도입됐다는 뜻이에요. 개발할 때 API 호출이 필요하면 이 기능을 활용해보세요. 예전에는 XMLHttpRequest나 다른 라이브러리를 많이 썼는데, `fetch`는 Promise 기반이라 비동기 처리가 훨씬 깔끔해져서 요즘은 표준처럼 쓰이고 있답니다.

Posts