# unauthorized 함수 사용법

Next.js에서 `unauthorized` 함수는 권한 문제가 발생했을 때 401 에러 페이지를 보여주는 역할을 해요. 즉, 사용자가 인증되지 않았을 경우에 적절히 오류를 처리할 수 있게 도와주는 거죠. 특히 인증 오류가 생겼을 때 기본으로 제공되는 UI 말고, 직접 `unauthorized.js` 파일을 만들어서 커스텀 디자인으로 바꿔줄 수도 있어요!

### 사용 준비: experimental 옵션 켜기

이 `unauthorized` 함수 기능을 사용하려면, `next.config.js` 파일에 실험적 기능인 `authInterrupts` 옵션을 활성화해줘야 해요. 설정 방법은 간단해요:

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

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

export default nextConfig
```

이 옵션을 켜면 Next.js가 인증 관련 오류를 감지하고 자동으로 401 페이지를 렌더링해줘서, 훨씬 깔끔하게 권한 문제를 관리할 수 있습니다.

---

### 조금 더 알아보기

- `unauthorized.js` 파일을 통해 원하는 스타일이나 메시지로 401 페이지를 커스터마이징할 수 있으니, 사용자 경험에 맞게 꼭 만들어보세요!
- 이 기능은 Next.js 최신 버전에서 실험적으로 제공되고 있으니, 업데이트 내용과 안정성은 공식 문서를 계속 체크하는 게 좋아요.
- 만약 인증이 필수인 페이지에서 `unauthorized()`를 호출하면, 자동으로 401 페이지로 넘어가므로 별도의 라우팅 처리가 필요 없답니다.

이제 `unauthorized` 함수로 인증 이슈를 더 쉽게 처리할 수 있으니, 다음 프로젝트에 바로 적용해 보세요!


<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에서 인증 처리를 할 때 유용한 `unauthorized` 함수 사용법에 대해 살펴볼게요.

---

```js
import { verifySession } from '@/app/lib/dal'
import { unauthorized } from 'next/navigation'
 
export default async function DashboardPage() {
  const session = await verifySession()
 
  if (!session) {
    unauthorized()
  }
 
  // 로그인 된 사용자에게 대시보드 보여주기
  return (
    <main>
      <h1>Welcome to the Dashboard</h1>
      <p>Hi, {session.user.name}.</p>
    </main>
  )
}
```

위 코드는 서버 컴포넌트(Server Component)에서 세션을 확인하고, 인증된 사용자가 아니라면 `unauthorized()` 함수를 호출해서 접근을 차단하는 예제입니다. `unauthorized()`가 호출되면 보통 401 Unauthorized 상태 코드가 리턴되면서 페이지가 차단돼요.

여기서 중요한 점은 `unauthorized` 함수가 **Server Components, Server Actions, Route Handlers에서만 호출 가능하다**는 거예요. 그래서 클라이언트 컴포넌트나 루트 레이아웃(root layout) 같은 데서는 사용할 수 없으니 참고하세요!

---

### 조금 더 알아보기

- `unauthorized()` 함수는 Next.js의 라우팅 시스템과 자연스럽게 연동돼서 인증되지 않은 사용자를 즉시 차단해줍니다.
- 서버쪽에서 인증 로직을 처리하면 클라이언트로 불필요한 데이터가 노출되는 걸 막을 수 있어서 보안이 강화돼요.
- 루트 레이아웃에서는 인증 처리 로직 대신, 페이지별로 인증 컴포넌트를 따로 구분해서 사용하는 게 일반적입니다.

---

이처럼 서버 컴포넌트에서 인증 제어를 하면서 사용자 경험도 자연스럽게 유지할 수 있으니, 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>

## 예제들

### 로그인하지 않은 사용자에게 로그인 UI 보여주기

로그인하지 않은 사용자에게 로그인 UI를 보여주고 싶을 때는 `unauthorized` 함수를 활용할 수 있어요. 이 함수는 `unauthorized.js` 파일을 렌더링하는 역할을 하죠.

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

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

  if (!session) {
    unauthorized()
  }

  return <div>Dashboard</div>
}
```

위 코드에서 `verifySession()`은 사용자의 세션을 확인하는 함수에요. 세션이 없으면(즉, 로그인하지 않은 상태면) `unauthorized()`를 호출해서 로그인 페이지 같은 별도의 UI를 보여줍니다.

---

조금 덧붙이자면, `unauthorized()`를 호출하면 보통 Next.js 앱에서 미리 정의해둔 로그인 화면으로 리다이렉트하거나 특정 컴포넌트를 렌더링하도록 설정해둔 경우가 많아요. 따라서 이 함수를 통해 인증되지 않은 사용자의 접근을 깔끔하게 차단하고, 친절한 로그인 유도 화면을 보여줄 수 있죠.

더불어, `verifySession` 같은 인증 관련 함수는 보통 서버 측에서 세션이나 토큰을 확인해서 로그인 상태를 판단하는데, Next.js의 서버 컴포넌트나 API 라우트에서 많이 사용됩니다. 만약 클라이언트 측에서 인증 상태를 확인해야 한다면, React의 상태 관리나 Context 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에서 인증되지 않은 사용자에게 401 Unauthorized 페이지를 보여주고, 서버 액션(Server Actions)에서 인증 검증을 하는 방법을 다뤄볼게요.

## 401 Unauthorized 페이지 만들기

먼저, 인증되지 않은 사용자가 접근했을 때 보여줄 페이지를 만들어볼게요. `UnauthorizedPage` 컴포넌트는 이렇게 생겼어요.

```jsx
import Login from '@/app/components/Login'

export default function UnauthorizedPage() {
  return (
    <main>
      <h1>401 - Unauthorized</h1>
      <p>이 페이지에 접근하려면 로그인이 필요해요.</p>
      <Login />
    </main>
  )
}
```

여기서 중요한 점은 `Login` 컴포넌트를 함께 렌더링해서, 사용자가 바로 로그인할 수 있는 UI를 제공하는 거예요. 사용자 경험이 훨씬 좋아지겠죠? 만약 로그인 UI가 별도로 없다면, 간단한 로그인 버튼이나 링크를 만들어도 괜찮아요.

## 서버 액션에서 인증 검사하기

이제 조금 더 심화된 내용으로, Next.js의 서버 액션(Server Actions)을 활용해 인증된 사용자만 특정 작업(예: 프로필 업데이트)을 할 수 있도록 제한하는 코드를 알아볼게요.

```js
'use server'

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

export async function updateProfile(data: FormData) {
  const session = await verifySession()

  // 인증되지 않은 경우 401 에러로 처리
  if (!session) {
    unauthorized()
  }

  // 인증된 경우 mutation 로직 진행
  // 실제 업데이트 로직 작성
}
```

### 여기서 주목할 점!

- `verifySession()` 함수는 사용자의 세션 정보를 확인해주는 커스텀 함수예요. 일반적으로 토큰이나 쿠키 정보를 검증해서 로그인 상태를 판단합니다.
- `unauthorized()` 함수는 Next.js 내장 네비게이션 함수로, 호출 시 401 Unauthorized 상태를 반환하고 해당 페이지로 리다이렉트해줍니다.
- 이렇게 하면 클라이언트 사이드에서 무작정 요청이 들어오는 걸 방지하고, 서버단에서 확실하게 검증할 수 있겠죠?

---

### 추가 팁

- 서버 액션은 React Server Components와 매우 잘 어울립니다. 서버에서 바로 데이터를 검증하고 변경할 수 있어 보안성을 높일 수 있어요.
- 만약 더 복잡한 인증 로직(예: 권한 레벨, 역할 기반 접근 제어 등)을 추가해야 한다면, `verifySession()` 함수 확장과 함께 별도의 미들웨어를 만들어 관리하는 걸 추천합니다.
- 에러 페이지 UI를 꾸밀 때는 사용자가 왜 접근이 제한됐는지 명확히 알 수 있도록 친절한 메시지를 넣는 게 좋아요.

---

이번 포스트를 통해 Next.js 13+에서 인증 관련 에러 핸들링과 서버 액션 내 인증 체크를 어떻게 구현하는지 감 잡으셨으면 좋겠네요! 실제로 적용해보면서 필요한 부분을 커스터마이즈해 보세요. 궁금한 점 있으면 댓글로 남겨주세요 :)


<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>

### Route Handlers에서 데이터 가져오기

Next.js에서 Route Handlers를 사용하면 인증된 사용자만 특정 API 엔드포인트에 접근하도록 쉽게 제한할 수 있어요. 특히, `unauthorized` 함수를 활용하면 인증이 안 된 사용자는 자동으로 401 에러 페이지를 보여주도록 할 수 있답니다.

```js
import { NextRequest, NextResponse } from 'next/server'
import { verifySession } from '@/app/lib/dal'
import { unauthorized } from 'next/navigation'
 
export async function GET(req: NextRequest): Promise<NextResponse> {
  // 사용자의 세션을 검증합니다.
  const session = await verifySession()
 
  // 세션이 없으면 401 상태 코드를 반환하면서 unauthorized.tsx 컴포넌트를 렌더링합니다.
  if (!session) {
    unauthorized()
  }
 
  // 필요한 데이터를 가져오는 로직을 작성하세요.
  // ...
}
```

이렇게 하면 인증이 되어야만 GET 요청에 접근할 수 있죠. `unauthorized()`를 호출하면 Next.js가 자동으로 401 상태와 함께 지정한 `unauthorized.tsx` 페이지를 보여주니까, 사용자 경험도 좋고 보안도 챙길 수 있어요.

추가로, `verifySession()` 같은 함수는 여러분 프로젝트 상황에 맞게 세션 검증 로직을 작성해야 하는데, 보통은 JWT 토큰 검사, 쿠키 확인, 데이터베이스 조회 같은 작업이 포함될 수 있어요. 인증 체크 로직이 서버 사이드에서 확실히 구동되니 클라이언트보다 훨씬 안전하답니다.

**참고:** `unauthorized()`는 라우트 핸들러에서 사용 가능한 함수로, 이 함수 호출 이후에는 응답을 작성하지 않아도 Next.js가 알아서 401 응답을 처리해 줘요.

---

다음에는 이 기능이 어떤 버전부터 지원되는지, 그리고 더 복잡한 인증 시나리오들에 대해 이야기해볼게요. 개발하면서 궁금한 점이 있으면 언제든 질문해 주세요!


<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>

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

여기서 `unauthorized`라는 게 새로 추가됐다고 해요. 보통 웹 개발이나 API 쪽에서 `unauthorized`는 인증이 필요한 리소스에 대해 권한이 없을 때 발생하는 상태를 말하는데요. 이번 버전(`v15.1.0`)에 이 기능이나 상태가 새로 추가된 듯해요. API를 다루다 보면 401 Unauthorized 상태 코드를 다루는 일이 많으니, 이 부분을 참고해두면 좋아요! 만약 이 변화가 특정 라이브러리나 프레임워크에 관한 거라면, 공식 문서를 한 번 확인해서 구체적인 사용법도 알아두면 도움이 될 거예요.

Nextjs 15에서 unauthorized 함수 권한 처리하는 방법

# unstable_cache 함수 소개

> 참고: 이 API는 아직 불안정 버전이며, 안정화되면 use cache라는 새로운 API로 대체될 예정이에요.

`unstable_cache`는 데이터베이스 쿼리처럼 비용이 많이 드는 작업 결과를 캐싱해서, 여러 요청 간에 그 결과를 재사용할 수 있게 도와주는 함수입니다. 덕분에 서버나 클라이언트에서 반복적인 작업을 줄여 성능을 개선할 수 있죠.

예를 들어, 사용자 정보를 데이터베이스에서 가져오는 작업이 있다고 할 때, `unstable_cache`로 감싸면 한 번 캐시된 결과를 재사용해서 같은 데이터를 다시 가져올 때 시간을 아낄 수 있어요.

아래 코드를 볼게요.

```js
import { getUser } from './data';
import { unstable_cache } from 'next/cache';

const getCachedUser = unstable_cache(
  async (id) => getUser(id),
  ['my-app-user']
);

export default async function Component({ userID }) {
  const user = await getCachedUser(userID);
  // ...
}
```

위 예제에서는 `getUser`라는 비싼 연산(사용자 정보 조회 함수)을 `unstable_cache`로 감싸서 `getCachedUser`라는 캐시된 함수를 만들었어요. 그 후 `Component` 컴포넌트 내에서 `getCachedUser`를 통해 빠르게 캐시된 사용자 정보를 받아올 수 있습니다.

---

## 조금 더 알아두면 좋은 점들

- `unstable_cache`의 두 번째 인자인 배열(`['my-app-user']`)은 캐시 키로 사용돼요. 이 키를 통해 캐시를 그룹화하거나 특정 조건에 따라 캐시를 재사용하거나 갱신할 수 있어요.
- 이 API는 아직 실험적이므로, 향후 Next.js 업데이트 시 API가 변경될 수 있다는 점 참고하세요.
- 캐시되는 데이터가 민감하거나 동적으로 자주 바뀌는 경우, 적절한 만료 전략과 무효화 로직이 꼭 필요해요.
- React 서버 컴포넌트에서 특히 유용하게 사용할 수 있는데, 서버 측에서 불필요하게 중복된 데이터 로드를 줄여 페이지 렌더링 속도를 높여줍니다.

이처럼 `unstable_cache`는 데이터 요청을 줄여 성능을 개선하는 좋은 수단이에요. 다만 안정적인 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>

> 알아두면 좋은 점:
캐시 범위 내에서 헤더나 쿠키 같은 동적인 데이터 소스에 접근하는 것은 지원되지 않습니다. 만약 캐시된 함수 안에서 이런 데이터가 필요하다면, 캐시 함수 외부에서 헤더를 받아서 필요한 동적 데이터를 함수 인자로 전달하는 방식을 사용하세요.
이 API는 Next.js의 내장 데이터 캐시 기능을 활용하여 요청이나 배포가 바뀌어도 결과를 유지합니다.

> 경고: 이 API는 아직 불안정한 상태이며 앞으로 변경될 수 있습니다. API가 안정화되면 마이그레이션 문서와 코드 변환 도구(codemods)를 제공할 예정입니다.

## 파라미터 설명

```js
const data = unstable_cache(fetchData, keyParts, options)()
```

위 코드는 `unstable_cache`라는 함수를 사용해 데이터를 캐싱하는 예시인데요, 여기서 각 인자가 무엇을 의미하는지 조금 더 자세히 알려드릴게요.

| 파라미터명  | 설명                                   |
|-------------|--------------------------------------|
| `fetchData` | 캐시할 데이터를 가져오는 함수          |
| `keyParts`  | 캐시 키를 구성하는 값 혹은 배열 (캐시 식별자 역할) |
| `options`   | 캐싱 동작을 제어하는 옵션 (예: 만료 시간 등)      |

이 함수를 호출하면 `fetchData` 함수가 반환하는 결과를 캐시에 저장해 두고, 다음부터는 같은 키로 요청할 때 캐시된 값을 재사용합니다. 서버 사이드 렌더링이나 API 라우트에서 자주 사용하는 패턴이죠.

> 팁!
동적 데이터를 다뤄야 할 때 헤더나 쿠키를 함수 외부에서 받아 인자로 넘기는 걸 꼭 기억하세요! 그래야 캐시가 잘 작동하면서도 필요한 동적 정보를 사용할 수 있습니다.

또한, `unstable_cache`는 아직 실험적인 기능이라 버전 업데이트 시 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>

fetchData: 비동기 함수로, 캐싱하려는 데이터를 가져와야 해요. 이 함수는 반드시 Promise를 반환해야 합니다.  
keyParts: 캐시 식별을 좀 더 세분화하기 위한 추가 키 배열이에요. 기본적으로 unstable_cache는 함수 인자와 함수의 문자열화된 버전을 캐시 키로 사용합니다. 대부분의 경우 선택 사항이지만, 매개변수로 전달하지 않는 외부 변수를 사용할 때 꼭 필요해요. 특히 클로저로 사용하는 변수는 여기 꼭 넣어줘야 합니다.  
options: 캐시 동작을 제어하는 객체인데, 다음과 같은 속성을 가질 수 있어요:
- tags: 캐시 무효화를 제어하는 데 사용하는 태그의 배열입니다. Next.js는 이 태그를 함수의 고유 식별자로 사용하지는 않아요.
- revalidate: 캐시를 다시 검증할 시간(초)입니다. 생략하거나 false를 전달하면 무기한 캐시하거나, revalidateTag() 또는 revalidatePath()가 호출될 때까지 캐시가 유지돼요.

---

### 반환값

unstable_cache는 호출 시 캐시된 데이터를 반환하는 함수(비동기)를 리턴합니다. 만약 캐시에 데이터가 없으면, 전달한 함수가 호출되고 결과가 캐시되어 반환됩니다.

---

## 예시

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

const fetchUsers = unstable_cache(async (page) => {
  const res = await fetch(`/api/users?page=${page}`);
  if (!res.ok) throw new Error('Failed to fetch users');
  return res.json();
}, {
  revalidate: 60,  // 60초마다 캐시 재검증
  tags: ['users'],
});

export async function getData() {
  const users = await fetchUsers(1);
  return users;
}
```

---

### 추가 팁!  
- `keyParts`는 캐시 키 생성 시 핵심적인 역할을 하는데, 예를 들어 전역 상태나 설정 값을 참조할 때 꼭 넣어주면 캐시가 꼬이는 걸 방지할 수 있어요.  
- `revalidate`를 너무 짧게 설정하면 캐시 효율이 떨어지고, 너무 길게 하면 오래된 데이터를 쓰게 되니 상황에 맞게 적절히 조절해주시는 게 좋아요!  
- `tags`는 나중에 특정 태그에 해당하는 캐시를 한 번에 무효화할 때 유용합니다. 예를 들어 사용자 관련 데이터가 변했을 때 'users' 태그를 가진 모든 캐시를 리셋할 수 있죠.  

캐시를 잘 활용하면 서버 부담도 줄이고, 사용자 경험도 훨씬 좋아질 테니 꼭 한번 시도해보세요!


<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에서 `unstable_cache`라는 캐싱 함수가 어떻게 쓰이는지 간단하게 살펴볼게요. 코드 예제를 보면서 함께 이해해봐요!

```js
import { unstable_cache } from 'next/cache'
 
export default async function Page({
  params,
}: {
  params: Promise<{ userId: string }>
}) {
  const { userId } = await params
  const getCachedUser = unstable_cache(
    async () => {
      return { id: userId }
    },
    [userId], // userId를 캐시 키에 포함해서 특정 사용자 데이터를 캐싱
    {
      tags: ['users'], // 태그로 캐시 그룹 지정, 나중에 태그 기반으로 재검증 가능
      revalidate: 60,  // 60초 후 캐시 자동 무효화(재요청 시 다시 호출)
    }
  )

  //...
}
```

### 이 코드가 하는 일은?

- `unstable_cache` 함수는 Next.js에서 제공하는 비공식(unstable) 캐시 함수예요.
- 첫 번째 인자는 실제 실행할 비동기 함수 (이 경우 `userId`를 받아 간단한 객체를 반환).
- 두 번째 인자는 캐시 키를 결정하는 배열로, `userId`가 바뀌면 캐시도 새로 생성됩니다.
- 세 번째 옵션 객체에는 `tags`와 `revalidate` 같은 설정들이 있어요.
  - `tags`는 특정 그룹으로 묶어, 같은 태그를 가진 캐시들을 한 번에 무효화 할 때 사용 가능.
  - `revalidate`는 위 캐시가 자동으로 재갱신되는 시간(초) 설정입니다.

### 제가 더 알려드리고 싶은 점!

- `unstable_cache`가 "unstable"인 이유는 아직 공식 API가 완전히 안정화된 게 아니기 때문이에요. 그러니 프로덕션용으로 쓸 때는 주의가 필요하겠죠.
- 하지만 Next.js 14부터 도입된 이 기능은 서버 컴포넌트나 API 라우트에서 데이터 중복 호출을 줄이고, 성능 최적화에 꽤 도움을 줄 수 있어요.
- 또, 태그 기반 캐싱 덕분에 관련된 여러 데이터들을 한 번에 무효화하는 전략을 쉽게 구현할 수 있답니다.
- 캐싱 정책을 잘 설계하면 페이지 렌더링 속도가 확실히 빨라지니, 꼭 자기 프로젝트에 맞춰 실험해 보세요!

---

## 버전 히스토리

| Version   | Changes                  |
|-----------|--------------------------|
| v14.0.0   | `unstable_cache` 도입   |

Next.js의 최신 기능들을 잘 활용해서 여러분 프로젝트도 한층 더 빠르고 똑똑하게 만들 수 있길 바랄게요!

Next.js 15 unstable_cache로 캐싱 최적화하는 최신 방법

# revalidateTag

`revalidateTag`은 특정 캐시 태그에 해당하는 데이터를 필요할 때 바로 지워서 새롭게 갱신할 수 있도록 도와주는 기능이에요.

> 알아두면 좋은 점:  
`revalidateTag`는 캐시를 바로 무효화하는 게 아니라, 해당 경로를 다음에 방문할 때 무효화가 이루어진다는 점이에요. 즉, 동적 라우트 세그먼트에 대해 `revalidateTag`를 호출해도 한꺼번에 많은 재검증이 바로 일어나는 것이 아니라, 경로를 실제로 다음에 방문할 때 무효화가 일어나는 방식입니다.

## Parameters (매개변수)

| 이름       | 타입      | 설명                                              |
|------------|-----------|---------------------------------------------------|
| tag        | string    | 무효화하려는 캐시 태그 이름                        |

---

### 좀 더 팁을 드리자면

`revalidateTag`는 데이터가 자주 바뀌는 페이지에서 유용해요. 예를 들어, 뉴스 사이트에서 특정 카테고리의 최신기사를 업데이트할 때, 전체 페이지를 모두 새로 고치기보다 관련된 태그만 무효화해서 효율적으로 캐시를 관리할 수 있죠.

그리고 동적 라우트가 많은 사이트에서는 무분별하게 캐시를 바로 무효화하는 것보다 이렇게 "다음 방문 시 무효화"하는 방식이 서버 부하를 줄이고, 사용자 경험도 부드럽게 만들어준답니다. 꼭 기억해두세요!


<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>

요즘 웹 개발하면서 캐시 재검증(revalidation) 기능을 많이 쓰게 되는데, 여기서 `revalidateTag`라는 함수가 있어요. 이 함수는 특정 캐시 태그를 기반으로 데이터를 다시 검증하도록 도와줍니다.

```js
revalidateTag(tag: string): void;
```

- **tag**: 캐시와 연결된 태그 이름을 문자열로 넣어주면 되는데, 최대 256자까지 가능합니다. 그리고 대소문자를 구분하니 주의하세요.

또한, 데이터를 요청할 때 `fetch` 함수에서 태그를 붙여서 쓸 수도 있어요:

```js
fetch(url, { next: { tags: [...] } });
```

이렇게 하면 해당 요청과 연관된 캐시 태그를 쉽게 관리할 수 있어서, `revalidateTag`로 특정 태그가 붙은 모든 데이터를 한 번에 재검증할 수 있답니다.

---

### 추가 팁!

- 태그를 잘 관리하면 서버 부담을 줄이면서 최신 데이터를 유지할 수 있어요.
- 태그 이름은 간결하고 직관적으로 만드는 게 좋아요. 예를 들어, `user-profile-123` 같은 식으로요.
- 태그 재검증 기능은 Next.js 13 이하 버전에선 experimental로 제공되기도 하니, 항상 버전별 문서 확인도 해보세요!  

이처럼 캐시 관리에 태그를 활용하면, 데이터 일관성 유지와 성능 향상에 큰 도움이 된답니다. 꼭 활용해보세요!


<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>

## 반환값

`revalidateTag` 함수는 반환값이 없어요.

## 예제

### 서버 액션에서 사용하기

`revalidateTag` 함수를 서버 액션(Server Action) 내에서 사용할 때는 보통 데이터가 바뀌었을 때 특정 태그와 관련된 캐시를 재검증(revalidate)할 때 사용해요. 서버 쪽에서 데이터를 업데이트한 뒤 클라이언트 측에서 최신 데이터를 받도록 만드는 역할이죠.

예를 들어, 블로그 글을 수정하거나 댓글을 추가했을 때 관련된 페이지나 API 응답 캐시가 최신 상태로 유지되게 하기 위해 쓸 수 있어요.

```js
'use server';

import { revalidateTag } from 'next/cache';

export async function updatePost(data) {
  // 데이터 업데이트 로직 (DB에 저장 등)
  
  revalidateTag('blog-post');

  // 반환값이 없는 함수입니다.
}
```

> TIP: `revalidateTag`는 반환값이 없어서 함수 호출 직후엔 결과를 받을 필요가 없고, 재검증 작업은 백그라운드에서 조용히 처리돼요. 그래서 함수 호출 뒤 별도의 에러 핸들링도 필요 없는 편이랍니다.

이렇게 서버 액션과 함께 쓰면, 사용자 입장에선 데이터가 실시간처럼 빠르게 반영되는 경험을 할 수 있어서 좋아요!


<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에서 서버에서 캐시 관리를 좀 더 세밀하게 할 수 있는 `revalidateTag` 기능에 대해 이야기해볼게요.

기본적으로 Next.js에서는 페이지나 데이터를 변경하면 전체를 다시 빌드하거나 리렌더링하기도 하죠? 근데 때로는 특정 태그에 해당하는 데이터만 부분적으로 다시 캐시를 갱신하고 싶을 때가 있어요. 이럴 땐 `revalidateTag`를 사용하면 아주 유용합니다.

---

### 1. 폼 제출 후 캐시 태그 재검증하기

```js
'use server'

import { revalidateTag } from 'next/cache'

export default async function submit() {
  await addPost()           // 새로운 게시글 추가 함수 (가정)
  revalidateTag('posts')    // 'posts'라는 태그가 붙은 부분만 캐시를 재검증해줘요
}
```

여기서 `addPost`는 새 글을 데이터베이스나 저장소에 추가하는 비동기 함수라고 생각하면 됩니다. 글이 성공적으로 추가된 뒤, `revalidateTag('posts')`를 호출해서 'posts' 태그가 걸린 데이터나 페이지 캐시만 다시 유효하게 만들어줘요. 강력하죠?

---

### 2. Route Handler에서 동적으로 태그 재검증

```js
import type { NextRequest } from 'next/server'
import { revalidateTag } from 'next/cache'

export async function GET(request: NextRequest) {
  const tag = request.nextUrl.searchParams.get('tag')  // 쿼리에서 태그 가져오기
  revalidateTag(tag)                                   // 그 태그에 대해 재검증 호출
  return Response.json({ revalidated: true, now: Date.now() })
}
```

URL 쿼리 파라미터로 태그 값을 받아와서 해당 태그만 똑똑하게 재검증하는 API예요. 예를 들어 `/api/revalidate?tag=posts`로 요청하면 'posts' 태그를 가진 캐시만 갱신되겠죠.

---

### 왜 태그별 재검증이 좋은가요?

- **성능 최적화**: 전체 데이터를 다시 빌드하거나 전부 캐시 무효화하는 대신, 관련된 작은 단위만 관리할 수 있어서 서버 부담이 줄어들어요.
- **빠른 피드백 루프**: 자주 변경되는 데이터만 신속하게 반영할 수 있어 사용자 경험이 좋아집니다.
- **코드 가독성 & 유지보수성 향상**: 데이터 모델별로 태그를 분리해서 관리하면, 어떤 부분이 업데이트됐는지 명확해져서 협업에도 유리해요.

---

저는 개인적으로 이 기능을 도입할 때, 아래 몇 가지도 같이 생각해보는데요!

| 팁 | 설명 |
| --- | --- |
| 태그 네이밍 규칙 만들기 | `posts`, `users`, `comments` 등 명확하고 일관된 이름을 쓰면 좋습니다. |
| 태그별 작업 분리 | 특정 동작마다 어떤 태그를 재검증해야 하는지 문서화해두면 편해요. |
| 에러 핸들링 강화 | `revalidateTag`가 실패할 경우 로깅하거나 재시도 로직을 넣는 것도 추천합니다. |

---

Next.js에서 서버 캐시와 관련해 고민중이라면, `revalidateTag` 방법 꼭 써보세요! 이 작은 툴 하나로 데이터 최신화 작업이 훨씬 수월해질 겁니다. 나중에 더 구체적인 적용 사례도 공유해드릴게요. 궁금한 점 있으면 언제든 댓글로 남겨주세요!

Next.js 15에서 특정 캐시 태그 갱신하는 방법 (revalidateTag)

# revalidatePath 정리해보기

revalidatePath는 특정 경로에 대해 캐시된 데이터를 즉시 갱신(무효화)할 수 있게 해주는 함수예요.

> 참고하면 좋은 점:
revalidatePath는 해당 경로를 다시 방문할 때 캐시를 무효화시켜줘요. 즉, 함수 호출 후 바로 캐시가 갈아엎어지는 게 아니라, 다음에 그 경로에 접근할 때 무효화가 적용된다는 뜻이죠. 동적 경로 세그먼트로 호출해도 한꺼번에 여러 경로가 즉시 무효화되는 게 아니라 '다음 방문 시점'부터 적용돼요.

현재는 서버 액션 내에서 revalidatePath를 쓰면, 클라이언트 사이드 라우터 캐시에 있는 모든 경로가 무효화되는 임시 동작을 하고 있어요. 이 부분은 향후 개선되어서 특정 경로에만 적용되도록 바뀔 거랍니다.

한편 서버 사이드 라우트 캐시에서는 특정 경로만 무효화하는 걸로 동작해요.

---

## 파라미터

(여기에 파라미터 관련 내용이 따라올 예정인데, 현재는 정보가 없네요.)

---

### 팁 하나 덧붙이자면요

이 기능은 예를 들어 게시글을 수정했을 때 수정된 내용이 바로 캐시에 반영되도록 강제로 갱신하고 싶을 때 많이 쓰이죠. 단, 재방문 시에 무효화가 되니까 페이지를 사용자에게 리다이렉트하거나, 클라이언트에서 다시 방문하게 만들어야 캐시 갱신 효과를 바로 볼 수 있다는 점 잊지 마세요! 

무효화를 즉시 반영해주는 것과는 조금 다르니까, 상황에 따라 적절히 활용해보세요.


<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>

```ts
revalidatePath(path: string, type?: 'page' | 'layout'): void;
```

- **path**: 다시 유효성 검사를 하고 싶은 데이터와 연결된 파일 시스템 경로 문자열입니다. 예를 들어, `/product/[slug]/page`처럼 동적 세그먼트를 포함할 수 있고, 혹은 `/product/123` 같은 실제 라우트 경로를 쓸 수도 있어요. 1024자 미만이어야 하고, 대소문자를 구분합니다.
- **type**: (선택적) `'page'` 또는 `'layout'` 문자열로, 재유효성 검사를 할 경로 유형을 정하는 거예요. 경로에 동적 세그먼트가 있다면 반드시 이 파라미터를 넣어야 합니다. 반대로, 동적 페이지 경로의 실제 라우트 예시(`/product/1`)를 줄 때는 넣지 않아야 합니다.

## 반환값

`revalidatePath` 함수는 값을 반환하지 않습니다. 즉, `void` 타입이에요.

---

### 한 마디 더!

`revalidatePath`는 Next.js에서 ISR(Incremental Static Regeneration)을 쓸 때, 특정 경로나 레이아웃을 수동으로 재검증하고 싶을 때 유용합니다. 페이지를 변경했을 때 빌드 전체를 다시 할 필요 없이 부분적으로 빠르게 리프레시하는 느낌이라 생각하면 편해요.

예를 들어, 어떤 상품 디테일 페이지 내용을 업데이트했을 때 해당 상품 페이지의 캐시만 재검증해서 최신 상태로 만들 수 있죠. 동적 경로가 섞인 경우에는 `type`을 꼭 신경 써서 넣어줘야 원하는 경로가 제대로 갱신됩니다.

개발 중에는 이 함수를 잘 활용하면 페이지 리빌드 시간을 크게 단축시킬 수 있으니 꼭 기억해두세요!


<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 재검증하기

```js
import { revalidatePath } from 'next/cache'

revalidatePath('/blog/post-1')
```

위 코드는 `/blog/post-1` 경로를 다음 페이지 방문 시 재검증하도록 설정하는 방법이에요. 즉, 사용자가 해당 URL에 접속하면 콘텐츠가 최신 상태인지 Next.js가 다시 확인해서 캐시를 갱신하게 되는 거죠.

추가로, revalidatePath는 아주 유용한 함수인데요, 페이지 빌드 후에 데이터가 바뀌었을 때 해당 페이지를 다시 유효성 검사해서 최신 내용을 보여주고 싶을 때 자주 사용됩니다. 예를 들어, 블로그 글을 수정하는 CMS 관리 페이지에서 이 함수를 호출하면 변경된 글이 사용자에게 바로 반영되게 할 수 있어요.

그리고 한 가지 팁을 더 드리자면, revalidatePath 외에도 revalidateTag 같은 함수도 있는데, 여러 페이지에서 공통으로 쓰이는 데이터(예: 헤더, 푸터 정보)를 태그 단위로 재검증할 때 편리합니다. 상황에 맞게 잘 활용해보세요!


<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>

### 페이지 경로 재검증 (Revalidating A Page Path)

```js
import { revalidatePath } from 'next/cache'

revalidatePath('/blog/[slug]', 'page')
// 또는 라우트 그룹을 사용할 때
revalidatePath('/(main)/blog/[slug]', 'page')
```

이 코드는 특정 페이지 파일과 일치하는 URL이 다음에 방문할 때 다시 검증하도록 만들어줍니다. 쉽게 말해, 해당 경로에 있는 페이지가 업데이트되었을 때, 다음 방문부터 최신 내용이 반영되도록 하는 기능이에요.

단, 중요한 점은 이 함수가 딱 지정한 경로에만 유효하다는 거예요. 예를 들어 `/blog/[slug]`를 재검증한다고 해서 `/blog/[slug]/[author]` 같은 하위 경로까지 자동으로 재검증되지 않습니다. 필요할 경우 하위 경로도 별도로 재검증해줘야 해요.

---

### 재검증에 대해 한마디 더!

이 기능은 SSR(서버 사이드 렌더링)이나 ISR(Incremental Static Regeneration)을 활용하는 프로젝트에서 자주 쓰입니다. 예를 들어, 블로그 글을 수정했을 때, 방문자가 새로 페이지를 요청하면 최신 버전을 보여주고 싶을 때 유용하죠.

하지만 너무 많은 경로에 대해 자주 재검증을 걸면 서버 부하가 늘 수 있으니, 꼭 필요한 경로에만 적절히 활용하는 게 좋습니다.

---

### 재검증 레이아웃 경로 (Revalidating A Layout Path)

(다음 섹션에서 계속 이어서 작성할게요!)


<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에서 제공하는 revalidatePath 함수에 대해 간단히 이야기해볼게요. 이 함수는 특정 경로와 그 경로에 연결된 레이아웃을 기준으로 페이지를 다시 검증(리빌드)하는 작업을 해줍니다.

```js
import { revalidatePath } from 'next/cache'

revalidatePath('/blog/[slug]', 'layout')
// 또는 경로 그룹 사용 시
revalidatePath('/(main)/post/[slug]', 'layout')
```

위 코드는 `/blog/[slug]`에 해당하는 레이아웃 파일을 기준으로, 해당 경로뿐만 아니라 그 경로 하위에 있는 다른 페이지들도 다음 방문 시 자동으로 다시 리빌드되게 해줍니다. 예를 들어 `/blog/[slug]/[another]` 같은 하위 경로도 포함되겠죠.

### 모든 데이터를 재검증 하는 방법

```js
import { revalidatePath } from 'next/cache'

revalidatePath('/', 'layout')
```

위처럼 루트 경로(`/`)에 대해 revalidatePath를 호출하면, 루트 레이아웃 아래에 속한 모든 페이지들이 다음 방문 시 다시 검증되어 최신 상태로 업데이트됩니다.

---

### 추가 팁!

- `revalidatePath`가 유용한 시점: 서버에서 어떤 데이터를 업데이트했는데 클라이언트 페이지에서 바로 최신 데이터가 반영되길 원할 때 써보세요.
- "layout" 옵션은 선택사항인데, 해당 경로의 레이아웃이 바뀌었을 때 그 변경 사항을 반영하기 위해 추가하는 경우가 많습니다.
- 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>

클라이언트 사이드 라우터 캐시를 지우고, 다음에 페이지를 방문할 때 데이터 캐시를 다시 검증하는 작업에 대해 이야기해볼게요.

### 서버 액션(Server Action)

```js
'use server'

import { revalidatePath } from 'next/cache'

export default async function submit() {
  await submitForm()
  revalidatePath('/')
}
```

위 코드는 간단하게 설명하면, 폼 제출 같은 서버 액션이 일어난 후에 특정 경로('/')의 캐시를 강제로 다시 검증(revalidate)하도록 해요. 이렇게 하면 클라이언트 쪽에 저장된 라우터 캐시를 초기화하고, 데이터가 최신 상태인지 확인할 수 있어서 사용자에게 더 정확한 정보를 제공할 수 있답니다.

**조금 더 풀어서 설명하자면**, `revalidatePath()` 함수는 Next.js의 서버 캐시를 특정 경로 기준으로 새로 고치는 역할을 해요. 이 덕분에, 예를 들어 데이터가 업데이트된 페이지를 구독하고 있는 사용자가, 다음 번 방문 때 반드시 최신 내용이 보여지도록 할 수 있죠.

### Route Handler

아래는 Route Handler에서 비슷한 맥락으로 쓰이는 코드의 예시입니다.

```js
import { revalidatePath } from 'next/cache'

export async function POST(request) {
  const data = await request.json()
  // 데이터 저장 로직 등 처리
  await saveData(data)

  // '/' 경로 캐시 재검증
  revalidatePath('/')

  return new Response('Success', { status: 200 })
}
```

Route Handler에서도 POST 요청 처리 후에 동일하게 `revalidatePath`를 호출해서 특정 경로의 캐시를 새로고침할 수 있어요.

---

> **TIP!**
>
> Next.js 13부터 새로운 데이터 패칭 방식과 서버 액션이 도입되면서, 이런 재검증 로직이 더 간편해졌어요. 특히 ISR(Incremental Static Regeneration)을 활용해 캐시를 누적하고, 필요한 순간에만 갱신하는 전략 덕분에 성능과 UX가 훨씬 좋아졌답니다. 적절한 타이밍에 `revalidatePath`를 호출하는 것이 핵심이에요!

필요하면 댓글이나 DM으로 질문 주세요. 더 친절하게 설명해드릴게요!


<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에서 ISR(Incremental Static Regeneration)을 활용할 일이 많아지면서, 특정 경로를 서버 사이드에서 동적으로 다시 빌드(재검증) 하는 방법에 대한 궁금증이 많아졌어요. 위에 코드가 그런 상황에서 유용한 예시라서 좀 쉽게 풀어서 설명해 드릴게요.

```js
import { revalidatePath } from 'next/cache'
import type { NextRequest } from 'next/server'

export async function GET(request: NextRequest) {
  // URL 쿼리에서 'path' 파라미터를 받아온다
  const path = request.nextUrl.searchParams.get('path')

  if (path) {
    // 해당 path를 Next.js에서 다시 빌드하도록 요청
    revalidatePath(path)
    return Response.json({ revalidated: true, now: Date.now() })
  }

  // path 파라미터가 없으면 에러 메시지 반환
  return Response.json({
    revalidated: false,
    now: Date.now(),
    message: 'Missing path to revalidate',
  })
}
```

### 코드 설명

- `revalidatePath`: Next.js 13에서 도입된 function으로, ISR에서 특정 경로를 다시 빌드하도록 시그널을 넣어줍니다.
- 이 API는 `GET` 요청을 받아서, 쿼리스트링에 `?path=/some-route` 형식으로 재검증할 경로를 전달하면 동작해요.
- 만약 `path`가 없으면 재검증을 할 수 없으니, 메시지를 되돌려주는 안전장치가 있죠.

---

### 여기서 더 알아두시면 좋은 점!

- `revalidatePath`는 내부적으로 Next.js의 캐시를 무효화해서, 다음에 해당 경로로 접근할 때 최신 버전의 페이지가 보여지게 만들어 줍니다.
- 재검증 요청을 API route처럼 만들어 두면, 관리자 페이지에서 "컨텐츠 업데이트" 버튼을 눌러 해당 페이지를 동적으로 최신화할 수 있어요.
- 주의할 점은, `path` 값은 Next.js 안에서 존재하는 페이지 경로여야 제대로 동작합니다. 없는 경로를 넣으면 에러는 안 나지만, 의미가 없겠죠.

---

### 보너스: 서버 컴포넌트라면 이런 식으로 쓰기도

Next.js 13 앱 디렉토리의 서버 컴포넌트에서는 이런 API route 없이 `revalidatePath`를 쓸 수 있습니다. 예를 들어, 폼 제출 후 해당 경로를 다시 검증하고 싶은 경우 이렇게요:

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

export async function updatePost(data: FormData) {
  // 글 업데이트 로직 수행
  const postId = data.get('postId') as string;

  // 포스트 페이지 재검증 요청
  revalidatePath(`/posts/${postId}`);
}
```

---

요약하자면, 오늘 보여드린 코드는 Next.js에서 특정 경로의 ISR 캐시를 수동으로 갱신하고 싶을 때 참 잘 쓰이는 방법입니다. 참고하시고, 필요할 때 활용해 보세요~!

Next.js 15에서 revalidatePath를 활용해 데이터 재검증하는 방법

# permanentRedirect 함수란?

permanentRedirect 함수는 사용자를 다른 URL로 영구적으로 이동시키고 싶을 때 사용하는 함수입니다. 이 함수는 Server Components, Client Components, Route Handlers, 그리고 Server Actions 등 다양한 환경에서 활용할 수 있어 아주 유용해요.

## 어떻게 동작할까?

- **스트리밍(streaming) 환경에서 사용하면?**  
  클라이언트 쪽에서 리다이렉트를 실행할 수 있도록 `<meta>` 태그를 삽입해줍니다. 즉, 브라우저가 이 태그를 보고 자동으로 원하는 URL로 이동하게 돼요.

- **서버 액션(Server Action)에서 사용하면?**  
  호출자에게 303 HTTP 리다이렉트 응답을 보내요. 303 코드는 "See Other"라는 의미로, 주로 POST 요청 후 GET 요청으로 리다이렉션할 때 씁니다.

- **그 외 경우에는?**  
  호출자에게 308 (Permanent Redirect) 응답을 보냅니다. 308은 영구적인 이동을 의미하므로 SEO나 캐싱에 좋은 영향을 줄 수 있답니다.

## 리다이렉트와 다르게 자원(리소스)이 없을 때는?

만약 요청한 페이지나 자원이 아예 없다면 permanentRedirect 대신 **notFound** 함수를 사용하세요. 이 함수는 404 페이지를 띄워주기 때문에 사용자 경험 측면에서 더 적절합니다.

---

이렇게 permanentRedirect 함수를 적절히 활용하면 사용자 흐름을 자연스럽게 제어할 수 있어요. 예를 들어, 회원 인증이 필요한 페이지에 인증되지 않은 사용자가 접근할 때 로그인 페이지로 영구 리다이렉트를 걸어줄 수도 있겠죠?

마지막으로, 리다이렉트를 할 때는 SEO(검색 엔진 최적화) 영향도 생각하면서 301(또는 Next.js에서는 308)으로 영구 리다이렉트할지, 302나 303으로 일시적 리다이렉트할지 결정하는 게 중요합니다.

혹시 더 궁금한 점 있으면 언제든 질문해 주세요!


<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>

> 참고할 만한 정보: 만약 308 (영구) 리다이렉트 대신 307 (임시) 리다이렉트를 사용하고 싶다면, `redirect` 함수를 사용하면 됩니다.

## 매개변수(Parameters)

`permanentRedirect` 함수는 두 개의 인자를 받습니다:

```js
permanentRedirect(path, type)
```

- `path`: 리다이렉트할 URL 경로를 지정해요.
- `type`: 리다이렉트의 종류를 나타내며, 보통 308이 기본값입니다.

---
여기서 잠깐!  
307과 308의 차이를 간단히 설명하자면, 307은 임시 리다이렉트로, 추후 경로가 원래대로 돌아올 가능성이 있을 때 쓰는 게 좋고요, 308은 영구 리다이렉트로 검색엔진 등에 "이 경로가 앞으로 쭉 이곳이다" 하고 명확하게 알려주는 용도로 좋아요.  
만약 서비스가 완전히 이전됐거나 URL 구조를 아예 바꾸었다면 308을, 잠깐 다른 페이지로 임시 이동시키는 경우에는 307을 선택하는 걸 추천합니다!


<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>

다음은 `permanentRedirect` 함수에서 사용하는 파라미터에 관한 설명입니다:

| Parameter | Type | Description |
| --- | --- | --- |
| `path` | `string` | 리다이렉트 할 URL입니다. 상대 경로나 절대 경로 모두 가능합니다. |
| `type` | `'replace'` (기본값) 또는 `'push'` (Server Actions에서는 기본값) | 리다이렉트 방식을 지정합니다. |

기본적으로, Server Actions에서는 `push` 방식을 사용해 브라우저 히스토리 스택에 새 항목을 추가하고, 그 외의 경우에는 `replace` 방식으로 현재 URL을 히스토리 스택에서 바꿉니다. 만약 이 동작 방식을 바꾸고 싶다면 `type` 파라미터를 통해 지정할 수 있어요.

단, Server Components에서는 `type` 파라미터가 아무런 영향을 미치지 않습니다.

---

이 부분에서 조금 더 설명을 덧붙이자면, 리다이렉트 방식을 `push`로 하면 사용자가 뒤로가기 버튼을 눌렀을 때 리다이렉트 이전의 페이지로 돌아갈 수 있어요. 반면에 `replace`는 현재 페이지를 히스토리에서 교체하기 때문에 뒤로가기가 이전 페이지가 아니라 그 전의 페이지로 연결되죠. 상황에 따라 적절한 방식을 선택하는 게 중요해요.

## Returns
(이 부분은 원문에 내용이 없는데, 보통 함수가 반환하는 값 등에 대해 설명할 때 쓰입니다. 이 함수가 반환하는 값이 있다면 여기에 그 내용을 추가해 주세요!)

---

만약 이 함수의 반환 값이나 사용 예제가 궁금하시다면, 언제든지 질문해 주세요!


<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>

permanentRedirect는 값을 반환하지 않습니다.

## 예시

permanentRedirect() 함수를 호출하면 NEXT_REDIRECT 에러를 발생시키고, 이 에러는 현재 라우트 세그먼트의 렌더링을 중단시킵니다.

```js
import { permanentRedirect } from 'next/navigation'

async function fetchTeam(id) {
  const res = await fetch('https://...')
  if (!res.ok) return undefined
  return res.json()
}

export default async function Profile({ params }) {
  const { id } = await params
  const team = await fetchTeam(id)
  if (!team) {
    permanentRedirect('/login')
  }

  // ...
}
```

---

### 좀 더 쉽게 설명하자면

`permanentRedirect` 함수는 단순히 "여기로 영구적으로 이동해!" 라는 신호를 보내는 역할을 해요. 그래서 실제로는 값을 돌려주지 않고, 호출하는 순간 렌더링이 멈추고 Next.js가 알아서 지정한 경로로 이동시키죠.

이 점을 헷갈리지 말아야 해요. 예를 들어 `return permanentRedirect('/login')` 처럼 값으로 사용하려고 하면 안되고, 그냥 `permanentRedirect('/login')`만 호출하면 됩니다.

### 유용한 팁

- `permanentRedirect`는 주로 서버 컴포넌트에서 사용하며, 클라이언트 사이드에서는 `useRouter` 훅의 `router.replace()` 같은 함수를 사용해요.
- 영구 리다이렉트라는 게, 브라우저에게 "이 URL은 앞으로도 이 주소로만 접속하세요" 라고 알려주는 301 상태 코드로 동작합니다. SEO에도 긍정적인 영향을 줘요.
- 만약 임시 리다이렉트가 필요하다면 `redirect()` 함수를 사용하고, 이건 302로 동작합니다.

Next.js 13부터 도입된 새로운 라우팅과 네비게이션 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>

알면 좋은 팁: permanentRedirect를 사용할 때 꼭 return permanentRedirect()처럼 반환할 필요가 없어요. 이 함수가 TypeScript의 never 타입을 사용하기 때문인데요.

여기서 never 타입은 함수가 절대 정상적으로 종료되지 않는다는 걸 의미해요. 그래서 permanentRedirect()를 호출하면 함수 실행이 멈추고 리다이렉트가 바로 발생하니까, 굳이 return을 붙여서 값을 반환할 필요가 없는 거예요.

예를 들어 이렇게 써도 전혀 문제없답니다:

```typescript
import { permanentRedirect } from 'next/navigation';

function handler() {
  // 어떤 조건에 따라 리다이렉트가 필요하면
  permanentRedirect('/new-path');
  // 사실상 여기에 도달하지 않아요.
}
```

개발할 때 이런 점을 알아두면 코드가 좀 더 깔끔해지고, 불필요한 return 문을 빼서 가독성도 좋아질 수 있답니다!

Next.js 15에서 permanentRedirect를 사용하는 방법 

# 리다이렉트 (redirect)

웹 개발할 때, 사용자를 다른 페이지로 옮겨야 할 때가 있죠? 그럴 때 쓰는 게 바로 `redirect` 함수입니다. 이 함수는 사용자를 지정한 URL로 이동시키는 역할을 해요. 

`redirect`는 Server Components, Route Handlers, Server Actions 같은 서버 쪽에서 사용할 수 있어요. 그런데 쓰이는 상황에 따라 동작 방식이 약간 달라집니다.

- **스트리밍 컨텍스트에서 사용하면**: 클라이언트 쪽에 `<meta>` 태그를 넣어서 브라우저가 자동으로 리다이렉트 하게끔 합니다.
- **서버 액션(Server Action)에서 사용하면**: HTTP 303 (See Other) 상태 코드를 보내서 호출자에게 리다이렉트를 하라고 알려줍니다.
- **그 외 상황에서는**: HTTP 307 (Temporary Redirect) 상태 코드로 리다이렉트 합니다.

또한, 만약 요청한 리소스가 존재하지 않는 경우에는 `redirect` 대신 `notFound` 함수를 써서 404 페이지로 안내하는 게 깔끔한 방법입니다.

---

### 참고로 알아두면 좋을 팁

- `redirect`를 클라이언트 사이드에서만 쓰는 것과 서버 사이드에서 쓰는 것은 완전히 다르므로, 제대로 위치에 맞게 써야 합니다.
- 303과 307 상태 코드는 둘 다 리다이렉트이지만, 303은 POST 요청을 GET 요청으로 바꾸어 다시 요청하게 합니다. 반면 307은 원래 요청 메서드를 유지해서 리다이렉트해요.
- 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>

> 참고할 점:
서버 액션(Server Actions)과 라우트 핸들러(Route Handlers) 내에서 리다이렉트를 할 때는 try/catch 블록이 끝난 후에 호출하는 게 좋아요. 만약 307(임시 이동) 대신 308(영구 이동) HTTP 리다이렉트를 원한다면, redirect 함수 대신 permanentRedirect 함수를 사용하면 됩니다.

## redirect 함수 파라미터

redirect 함수는 총 두 개의 인자를 받습니다:

```js
redirect(path, type)
```

| 인자  | 설명                                            |
|-------|-------------------------------------------------|
| path  | 리다이렉트할 경로를 문자열 형태로 지정합니다.      |
| type  | 리다이렉트 HTTP 상태 코드를 숫자로 지정합니다. (예: 307 또는 308) |

> TIP!  
> 리다이렉트를 try/catch 안에서 바로 쓰면 의도치 않은 에러가 발생할 수 있으니 반드시 try/catch 블록 밖에서 호출하는 걸 권장해요. 그리고 308 리다이렉트는 클라이언트 쪽에서 캐싱이 되므로, 영구적으로 주소가 변경되었을 때 활용하면 좋아요!


<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>

| Parameter | Type | Description |
| --- | --- | --- |
| `path` | `string` | 리다이렉트할 URL 경로입니다. 상대 경로나 절대 경로 모두 사용할 수 있어요. |
| `type` | `'replace'` (기본값) 또는 `'push'` (Server Actions에서 기본값) | 리다이렉트 방식입니다. |

기본적으로 Server Actions에서는 `push` 방식을 사용해서 브라우저 히스토리에 새 항목을 추가하고, 그 외 환경에서는 `replace` 방식으로 현재 URL을 교체합니다. 만약 원하는 동작이 다르다면 `type` 파라미터를 지정해서 이 동작을 덮어쓸 수 있어요.

참고로, Server Components 내에서 사용할 때는 `type` 파라미터는 영향을 미치지 않습니다.

---

여기서 `push`와 `replace`에 대해 간단히 정리해볼게요. `push`는 사용자가 뒤로 가기 같은 내비게이션을 할 수 있게 히스토리에 새 페이지를 추가하는 방식이에요. 반면 `replace`는 지금 페이지를 새로운 URL로 교체하기 때문에 뒤로 가기를 눌러도 이전 URL로 돌아가지 못하죠. 상황에 따라 적절한 방식을 선택하는 게 중요하니 꼭 기억해두세요!


<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>

redirect 함수가 값을 반환하지 않는다는 점, 다들 알고 계신가요?

## 예시

### 서버 컴포넌트(Server Component)

redirect() 함수를 호출하면 NEXT_REDIRECT라는 에러가 발생하면서, 해당 함수가 호출된 라우트 세그먼트의 렌더링이 바로 종료됩니다.

---

좀 더 쉽게 설명하자면, 이 redirect() 함수는 단순히 '여기서 멈추고 이 주소로 이동해!'라고 브라우저에게 알려주는 역할이에요. 그래서 값을 돌려주는 게 아니라, 내부적으로 예외를 던져서 렌더링 과정을 중단시키고 리다이렉트를 처리하죠.

이 방식 덕분에 서버 컴포넌트 내에서 복잡한 조건에 따라 바로 리다이렉트가 가능해서, 불필요한 렌더링을 하지 않아 성능 면에서도 이득을 볼 수 있답니다.

참고로, 만약 이 함수를 클라이언트 컴포넌트에서 사용하려고 하면 작동하지 않으니 주의하세요! 서버 컴포넌트 내에서만 제대로 작동하는 점 기억해 주세요.


<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 13에서 서버 컴포넌트 내에서 데이터를 불러오고, 만약 데이터가 없으면 리다이렉트를 하는 예제예요.

```tsx
import { redirect } from 'next/navigation'

async function fetchTeam(id: string) {
  const res = await fetch('https://...')
  if (!res.ok) return undefined
  return res.json()
}

export default async function Profile({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const team = await fetchTeam(id)

  if (!team) {
    redirect('/login')
  }

  // ...
}
```

### 핵심 내용

- `redirect()` 함수는 `next/navigation`에서 제공하며, 조건에 따라 유저를 다른 페이지로 보내줄 때 사용해요.
- `return redirect()`처럼 반환하지 않아도 돼요. 왜냐하면 `redirect()` 함수가 TypeScript의 `never` 타입을 사용해서, 그 이후 코드는 실행되지 않는 것으로 처리되거든요.
- `params`가 `Promise<{ id: string }>` 타입인 이유는 Next.js에서 동적 라우트에서 params를 비동기로 받을 때 이렇게 작성하는 경우가 있어요.
- 데이터를 못 받아오면(`team`이 없으면) 로그인 페이지로 리다이렉트합니다.

### 추가 팁! Client Component에서의 redirect 사용

`redirect()` 함수는 서버 컴포넌트뿐만 아니라 클라이언트 컴포넌트에서도 바로 사용할 수 있어요. 보통 클라이언트 컴포넌트에서 리다이렉트를 하려면 `useRouter()`의 `push` 메서드를 썼는데, 사실 Next.js 13에서는 `redirect()`를 바로 써도 된답니다!

```tsx
'use client'
import { redirect } from 'next/navigation'

export default function MyClientComponent() {
  const isLoggedIn = false

  if (!isLoggedIn) {
    redirect('/login')
  }

  return <div>Welcome back!</div>
}
```

### 요약

| 기능                | 설명                              |
|---------------------|---------------------------------|
| `redirect()`        | 서버/클라이언트 컴포넌트 모두에서 사용 가능 |
| 반환값 없이 호출 가능 | TypeScript의 never 타입 덕분에 코드 중단 |
| 데이터 못받았을 때 사용 | 로그인 등 특정 페이지로 유도 가능          |

`redirect` 쓰면 조건에 따라 유저 경험을 자연스럽게 제어할 수 있어서, 로그인 상태 체크나 접근 권한 관리할 때 아주 유용하니 꼭 잘 익혀두세요!


<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 13에서 클라이언트 컴포넌트에서의 리다이렉션 처리 방법에 대해 이야기해볼게요.

---

### 기본 예제: 클라이언트에서 조건부 리다이렉트

```js
'use client'

import { redirect, usePathname } from 'next/navigation'

export function ClientRedirect() {
  const pathname = usePathname()

  if (pathname.startsWith('/admin') && !pathname.includes('/login')) {
    redirect('/admin/login')
  }

  return <div>Login Page</div>
}
```

이 코드의 핵심은 `usePathname`을 사용해서 현재 경로를 가져온 다음, `/admin` 경로면서 로그인 페이지가 아니면 바로 `/admin/login`으로 리다이렉트하는 거예요.

> 여기서 주의할 점은, 클라이언트 컴포넌트에서 `redirect`를 사용할 때 초기 SSR(Server-Side Rendering) 중에 호출되면 서버 사이드에서 리다이렉트가 일어난다는 사실이에요. 그래서 빠르고 깔끔한 리다이렉션 처리가 가능하죠.

---

### 이벤트 핸들러에서 리다이렉트하려면?

만약 버튼 클릭 같은 이벤트 핸들러 안에서 리다이렉트를 하고 싶다면, 그냥 이 코드처럼 하면 안 돼요:

```js
const pathname = usePathname();
if (...) {
  redirect('/somewhere')
}
```

왜냐하면 `redirect()`는 바로 리다이렉트가 일어나는데, 이벤트 핸들러는 비동기 처리 같은 다른 패턴을 사용해야 하거든요.

대신, `useRouter` 훅을 써서 프로그래밍적으로 경로를 이동하거나, 서버 액션(Server Action)을 활용하는 방식을 추천해요.

---

### 서버 액션과 폼 제출로 리다이렉트 하기

아래 예시는 서버 액션을 이용해서 폼 제출 시 리다이렉트 하는 방식입니다.

```js
'use client'

import { navigate } from './actions'

export function ClientRedirect() {
  return (
    <form action={navigate}>
      <input type="text" name="id" />
      <button>Submit</button>
    </form>
  )
}
```

이때 `navigate`는 서버 액션에서 클라이언트로 리다이렉트를 수행하도록 구현해야 해요. 이렇게 하면 폼을 제출하는 순간 서버 액션이 실행되고, 그 결과로 리다이렉트가 처리될 수 있죠.

---

### 정리

| 상황                            | 사용법                                   | 참고사항                                                   |
|-------------------------------|----------------------------------------|-----------------------------------------------------------|
| 클라이언트 컴포넌트에서 초기 경로 감지 후 리다이렉트  | `usePathname` + `redirect()`                | 초기 SSR 시 서버에서 리다이렉트 된다                       |
| 이벤트 핸들러 내에서 리다이렉트          | `useRouter().push()` 또는 서버 액션 활용       | `redirect()` 직접 호출은 불가, `useRouter`가 더 적합      |
| 폼 제출 후 서버에서 처리하며 리다이렉트         | 폼의 `action`으로 서버 액션 지정               | 서버 액션 내에서 리다이렉트 처리 가능                      |

---

### 추가 팁

- `useRouter`의 `push` 메서드는 클라이언트 사이드 네비게이션을 수행해서 페이지 전환 시 전체 페이지 리로딩이 없고 더 부드러운 사용자 경험을 제공해요.
- 서버 액션은 Next.js 13에서 도입된 개념인데, 클라이언트와 서버 코드를 자연스럽게 연동할 수 있도록 해 줘서 폼 제출이나 데이터 처리 후 리다이렉션, 데이터 갱신 작업에 아주 유용해요.

---

이렇게 클라이언트 컴포넌트에서 리다이렉트를 다룰 때는 렌더링 시점과 이벤트 처리 방식에 따라 적합한 방법을 선택하는 게 중요해요! 다음 프로젝트에서 바로 써먹어 보세요 :)


<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>

```js
'use server'

import { redirect } from 'next/navigation'

export async function navigate(data: FormData) {
  redirect(`/posts/${data.get('id')}`)
}
```

## FAQ

### redirect가 왜 307과 308 상태 코드를 사용하는 걸까?

redirect() 함수를 사용할 때, 상태 코드로 307(임시 리다이렉트)과 308(영구 리다이렉트)을 볼 수 있는데요. 사실 전통적으로는 임시 리다이렉트에 302, 영구 리다이렉트에 301 코드를 사용했었어요. 그런데 문제는, 많은 브라우저가 302를 이용한 리다이렉트 시 원래 요청 방식이 POST였어도 GET으로 바꿔버린다는 점이에요.

즉, POST 요청을 302 리다이렉트 하면, 브라우저가 POST가 아닌 GET 요청으로 전환해버려 의도한 동작과 달라질 수 있죠. 그래서 HTTP 명세에 따라, 원래 요청 메서드를 그대로 유지하며 리다이렉트 하도록 307(임시)과 308(영구)이 나온 거예요.

이렇게 307과 308 코드를 사용하면 POST 요청이 리다이렉트 될 때도 POST를 유지하기 때문에, 서버와 클라이언트 모두 예상 외 문제 없이 정상 동작할 수 있답니다.

---

추가로, 만약 여러분이 직접 리다이렉트 코드를 구현하거나 Next.js 같은 프레임워크 내부 동작을 이해하는 데 관심 있다면, 이런 상태 코드의 차이와 의미를 꼭 알아두는 게 좋아요. 특히 API 서버를 설계할 때, 데이터가 POST 요청으로 들어올 때 리다이렉트 후에도 메서드가 유지되어야 하는 상황이라면 307/308 상태 코드를 잘 활용하는 것이 중요합니다!


<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>

예를 들어, /users에서 /people로 리다이렉트하는 상황을 생각해볼게요. 만약 새로운 사용자를 만들기 위해 /users에 POST 요청을 보냈는데, 302 임시 리다이렉트 방식을 따르면 요청 메서드가 POST에서 GET으로 바뀌어 버려요. 이건 좀 말이 안 되죠. 왜냐하면, 새로운 사용자를 만들려면 /people에 POST 요청을 해야 하는데, 잘못 GET 요청이 되어버리니까요.

그래서 나온 게 307 상태 코드입니다. 이 코드는 요청 메서드를 POST로 그대로 유지시켜줘요.

| 상태 코드 | 설명                                  |
|-----------|-------------------------------------|
| 302       | 임시 리다이렉트, POST를 GET으로 변경 |
| 307       | 임시 리다이렉트, 요청 메서드 그대로 유지 (POST 유지) |

그리고 요즘 많이 사용하는 redirect() 메서드는 기본적으로 307 상태 코드를 사용해요. 덕분에 POST 요청이 리다이렉트돼도 메서드가 변경되지 않는 거죠.

---

참고로 303 상태 코드도 있는데요, 이건 POST 요청 후 다른 페이지로 리다이렉트할 때 주로 사용되고, 이때는 GET 방식으로 변경됩니다. 즉, 303은 'POST-리스폰스-GET' 패턴을 강제하는 느낌이고, 307은 메서드를 그대로 유지하려는 상황에 딱 맞아요.

이게 실제로 개발할 때 헷갈릴 수 있는데, 특히 API 서버를 만들거나, 폼 전송을 리다이렉트해서 처리할 때 꼭 알아두면 좋아요. 307을 사용하면 예상치 못한 요청 메서드 변경 때문에 발생하는 문제를 미연에 방지할 수 있거든요.


<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>

HTTP 리다이렉트에 대해 더 알아보기

## 버전 히스토리

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

---

HTTP 리다이렉트는 웹 개발할 때 정말 자주 마주치는 기능 중 하나예요. 간단히 말해서, 특정 URL에서 다른 URL로 자동으로 이동시키는 걸 말하죠. 예를 들어, 예전 주소에서 새 주소로 방문자를 안내하거나, HTTP에서 HTTPS로 보안 연결을 강제할 때도 사용하구요.

이번에 달라진 v13.0.0 버전에서는 `redirect` 기능이 새롭게 도입됐다고 하네요. 이 기능 덕분에 리다이렉트 구현이 더 간편해졌을 거라 기대됩니다. 코드를 깔끔하게 관리할 수 있고, 사용자 경험도 개선할 수 있으니까요.

만약 여러분이 서버 사이드나 프론트엔드 라우팅에서 리다이렉트를 다루고 있다면, 이번 업데이트 내용을 꼭 체크해 보세요! 혹시 리다이렉트를 처음 접한다면, 기본적인 301(영구 이동), 302(임시 이동) 상태 코드부터 이해하는 게 좋아요. 이를 통해 SEO 최적화도 잘 할 수 있답니다.

더 궁금한 점이나 구현 팁이 필요하면 언제든 물어봐 주세요!

Next.js 15에서 Redirect 기능 구현하는 방법

# notFound

`notFound` 함수는 특정 라우트 세그먼트 내에서 "찾을 수 없음" 페이지를 렌더링할 수 있게 해주고, 동시에 `<meta name="robots" content="noindex" />` 태그를 주입해서 검색엔진이 해당 페이지를 인덱싱하지 않도록 설정해 줍니다.

## notFound()

`notFound()` 함수를 호출하면 `NEXT_HTTP_ERROR_FALLBACK;404` 에러가 발생하면서 현재 라우트 세그먼트의 렌더링이 종료됩니다. 그런데 이런 에러를 처리하기 위해 "not-found" 파일을 지정해놓으면, 에러 대신 유저에게 보여줄 깔끔한 "페이지를 찾을 수 없습니다" UI를 해당 세그먼트 내에서 렌더링할 수 있어요.

---

추가로, Next.js 같은 프레임워크에서는 이 `notFound` 함수를 활용해서 유저가 잘못된 URL에 접근했을 때 단순한 404 페이지 대신, 맞춤형 디자인이나 메시지를 보여줄 수 있기 때문에 사용자 경험(UX)이 훨씬 좋아집니다. 그리고 SEO 측면에서도 `noindex` 메타 태그를 자동 주입해주니 검색엔진에 불필요한 페이지가 노출되는 것을 방지할 수 있답니다.

---

마지막으로, `notFound`를 사용할 때는 다음처럼 작성할 수 있어요:

```js
import { notFound } from 'next/navigation';

export default function Page({ params }) {
  const data = fetchData(params.id);

  if (!data) {
    notFound();
  }

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

데이터가 없을 때 `notFound()`를 호출해서 404 처리와 함께 적절한 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>

```js
import { notFound } from 'next/navigation'

async function fetchUser(id) {
  const res = await fetch('https://...')
  if (!res.ok) return undefined
  return res.json()
}

export default async function Profile({ params }) {
  const { id } = await params
  const user = await fetchUser(id)

  if (!user) {
    notFound()
  }

  // ...
}
```

> 참고로 알아두면 좋은 점: `notFound()` 함수는 `return notFound()`처럼 반드시 반환문과 함께 사용할 필요가 없어요. TypeScript의 `never` 타입 덕분에 함수 실행 후 더 이상 코드가 실행되지 않는다는 걸 타입 시스템이 알고 있기 때문이죠.

---

## 버전 히스토리

| 버전       | 변경 사항               |
|------------|------------------------|
| v13.0.0    | `notFound` 함수가 도입됨 |

---

### 조금 더 알아볼까요?

`notFound()` 함수는 Next.js의 새로워진 라우팅 시스템에서 404 페이지를 간편하게 렌더링할 수 있게 해주는데요. 예전에는 직접 `return <ErrorPage statusCode={404} />` 같은 식으로 처리하거나 서버 쪽에서 응답 상태를 관리해야 했죠. 

하지만 이제는 이렇게 데이터를 비동기로 가져오면서, 만약 데이터가 없으면 `notFound()`만 호출하면 페이지가 바로 404 페이지로 전환돼서 사용자 경험도 깔끔해졌어요.

또한, `notFound()`가 `never` 타입을 반환하는 덕분에 이후 코드는 실행되지 않으니, 따로 `return` 구문으로 감싸 주지 않아도 된다는 점은 개인적으로 매우 마음에 드는 부분입니다.

이외에도 Next.js 13부터는 이런 여러 편리한 API들이 추가되면서, 개발할 때 코드도 더 간결해지고, 에러 핸들링도 한결 직관적으로 할 수 있게 됐답니다!

Next.js 15에서 404 페이지 만드는 방법(notFound)

# NextResponse

NextResponse는 Web Response API를 확장한 것으로, 좀 더 편리하게 사용할 수 있는 메서드들이 추가된 Response 객체입니다. 기존의 Response 객체보다 훨씬 직관적이고 유용한 기능들을 제공해서, 특히 서버 사이드에서 많이 활용됩니다.

## cookies

NextResponse의 `cookies` 속성을 사용하면, 응답(Response)의 `Set-Cookie` 헤더를 읽거나 변경할 수 있어요. 즉, 클라이언트에게 보낼 쿠키를 쉽게 관리할 수 있다는 뜻이죠.

예를 들어, 서버에서 쿠키를 추가하거나 수정할 때 직접 헤더를 조작하는 것보다 훨씬 깔끔하게 쓸 수 있습니다.

```js
import { NextResponse } from 'next/server';

export function middleware(req) {
  const res = NextResponse.next();

  // 쿠키 읽기
  const token = req.cookies.get('token');

  // 쿠키 설정하기
  res.cookies.set('loggedIn', 'true', { path: '/', httpOnly: true });

  return res;
}
```

이처럼 NextResponse의 `cookies` API를 쓰면 쿠키를 딱 한 줄로 읽고 쓸 수 있어서, 복잡한 헤더 조작 없이도 쉽게 작업할 수 있답니다.

추가로, `cookies.set()` 메서드는 옵션으로 `httpOnly`, `secure`, `maxAge` 같은 여러 속성들을 받아서 보안이나 유효기간 설정도 간편해요.  
또한, Next.js 13부터는 미들웨어나 API 라우트 등 서버 환경에서 이런 NextResponse 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>

### set(name, value)

이 메서드는 이름(name)과 값(value)을 받아서 응답(response)에 쿠키를 설정해주는 역할을 해요.

예를 들어, 사용자가 어떤 배너를 다시 보지 않도록 설정하고 싶을 때 이렇게 활용할 수 있죠.

```js
// /home 경로로 들어오는 요청이 있을 때
let response = NextResponse.next()
// 'show-banner'라는 이름의 쿠키를 'false' 값으로 설정해서 배너 숨기기
response.cookies.set('show-banner', 'false')
// 이 응답에는 `Set-Cookie: show-banner=false; path=/home` 헤더가 포함되어 반환됩니다.
return response
```

여기서 중요한 점은 `response.cookies.set()`을 사용하면 쿠키가 응답 헤더에 `Set-Cookie` 형태로 추가된다는 거예요. 그리고 경로(path) 옵션은 기본적으로 요청된 경로와 동일하게 설정되기 때문에, 원하는 경로로 지정하려면 옵션을 명시해 주어야 해요.

```js
response.cookies.set('user-preference', 'dark-mode', { path: '/' })
```

이렇게 하면 쿠키가 모든 경로에서 유효하게 설정됩니다.

---

### get(name)

쿠키 값을 읽을 때는 `get(name)` 메서드를 사용해요. 예를 들어 사용자가 이전에 설정한 배너 표시 여부를 확인하고 싶을 때 사용할 수 있겠죠.

```js
const showBanner = request.cookies.get('show-banner')
```

이렇게 하면 `showBanner` 변수에 쿠키의 값이 담겨 오고, 없으면 `undefined`가 반환됩니다.

---

### 참고로!

- 쿠키는 클라이언트와 서버 사이에서 상태를 유지하는 간단한 방법이에요. 특히 사용자의 선호나 로그인 상태 같은 정보를 저장할 때 자주 사용되죠.
- Next.js 13부터는 `NextResponse` 객체를 통해 쿠키를 쉽게 다룰 수 있어서 편리해요.
- 보안 상 민감한 정보(예: 비밀번호, 토큰 등)는 절대 쿠키에 그냥 저장하면 안 되고 `HttpOnly`, `Secure` 옵션을 꼭 설정해야 해요.
- 또한 쿠키 용량 제한과 만료일 설정도 신경 써야 하고요.

필요하면 쿠키 설정에 `expires`, `maxAge`, `secure`, `httpOnly` 등의 옵션도 함께 활용해 보세요!


<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>

쿠키를 다룰 때 자주 쓰는 메서드인 `get()`과 `getAll()`에 대해 쉽게 설명해볼게요!

---

### `get()` 메서드

- **기능:** 쿠키 이름을 주면, 그 쿠키의 **값(value)** 을 가져와 줘요.
- **예외 상황:** 
  - 쿠키가 없다면 `undefined`를 반환해요.
  - 만약 한 이름으로 여러 개의 쿠키가 있으면, 맨 처음 쿠키의 값을 반환합니다.

예를 들어, `/home` 경로에서 들어오는 요청이 있다고 하고, 

```js
let response = NextResponse.next()
// 쿠키 중 { name: 'show-banner', value: 'false', Path: '/home' } 가 있다고 가정하면,
response.cookies.get('show-banner') // 'false' 반환
```

첫 번째 일치하는 쿠키 값을 리턴하니 정말 간편하죠?

---

### `getAll()` 메서드

- **기능:** 
  - 쿠키 이름을 주면, 이름에 해당하는 모든 쿠키들을 배열로 받아요.
  - 이름을 안 주면, **현재 응답(response)에 포함된 모든 쿠키**를 배열로 반환합니다.

이걸 활용하면 같은 이름으로 중복된 쿠키를 한꺼번에 다룰 수도 있고,
한번에 모든 쿠키를 살펴보기도 좋아요.

---

### 추가 꿀팁!

- 쿠키는 같은 이름이라도 경로나 도메인 범위가 다를 수 있다는 점 기억하세요! 그래서 중복된 이름의 쿠키가 있을 수 있거든요.
- `get()`는 첫 번째 쿠키만 가져오니까, 혹시 여러 개 있을 때 모두 확인하려면 `getAll()`을 쓰세요.
- 클라이언트에서 쿠키를 조작할 때는 보안 설정(예: HttpOnly, Secure)도 꼭 챙기는 게 좋아요.

꾸준히 쿠키를 잘 다루면 로그인, 알림 설정 등 중요한 기능들을 매끄럽게 만들 수 있답니다!


<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에서 response.cookies 다룰 때, 쿠키를 삭제하는 방법에 대해 간단하게 알려줄게요.

보통 쿠키를 삭제할 땐 set-cookie 헤더를 통해 만료된 상태로 만들어 보내잖아요? next.js 13부터는 NextResponse 객체가 쿠키 API를 제공해서, `response.cookies.delete('쿠키명')` 이렇게 한 줄로 쉽게 삭제가 가능해요.

```js
// /home 경로로 들어온 요청 처리 중
let response = NextResponse.next()
// 'experiments'라는 이름의 쿠키가 있다면 삭제합니다.
const deleted = response.cookies.delete('experiments') 
console.log(deleted) // 쿠키를 삭제했으면 true, 없으면 false 반환
```

여기서 `delete` 메서드는 실제 쿠키가 있으면 삭제 처리 후 `true`를 반환하고, 없으면 `false`를 반환해서 잘 삭제되었는지 확인할 수 있어요. 그리고 삭제할 때는 해당 쿠키의 path(경로)도 맞춰줘야 삭제가 제대로 되는데, 기본 path가 맞으면 굳이 지정 안 해도 돼요.

---

추가로 알아두면 좋은 점!

- `response.cookies.getAll()`로 response에 담긴 모든 쿠키를 배열로 쉽게 조회할 수 있어요.
- 쿠키 이름이 같으면, 여러 개의 쿠키가 배열로 반환됩니다. (`[{name, value, Path}, ...]`)
- 쿠키를 삭제할 때 특정 path나 domain도 설정해야 할 경우가 있으니, 필요하면 옵션도 같이 넘겨줄 수 있어요.

---

조금 더 쉽게 이해되도록 요약표를 만들었으니 참고하세요!

| 메서드                  | 설명                           | 반환값                |
|----------------------|------------------------------|-------------------|
| `response.cookies.getAll('쿠키명')` | 특정 이름의 모든 쿠키 조회           | 쿠키 배열               |
| `response.cookies.getAll()`        | 모든 쿠키 조회                    | 쿠키 배열               |
| `response.cookies.delete('쿠키명')` | 쿠키 삭제                       | 삭제 성공 시: `true`, 실패 시: `false` |

---

사실 개발할 때 쿠키 관리가 깔끔해야 나중에 디버깅하기도 편한데, next.js의 `response.cookies` 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>

## json() 함수 사용하기

Next.js에서 API 응답을 JSON 형태로 쉽게 만들어주는 `NextResponse.json()` 함수에 대해 알아볼게요.

```js
import { NextResponse } from 'next/server'
 
export async function GET(request: Request) {
  return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 })
}
```

위처럼 사용하면, 클라이언트에 `{ error: 'Internal Server Error' }`라는 JSON 데이터를 보내면서, HTTP 상태 코드를 500으로 설정할 수 있어요. 간단하죠?

참고로, `NextResponse.json()`은 내부적으로 `Content-Type` 헤더를 `application/json`으로 설정하니까, 따로 헤더 신경 쓸 필요가 없답니다.

---

## redirect() 함수 소개

`redirect()` 함수는 원하는 URL로 클라이언트를 리다이렉트할 때 사용해요. 서버에서 특정 조건이 충족되면 다른 페이지로 보내고 싶을 때 참 유용하죠.

예를 들어, 다음처럼 쓸 수 있습니다:

```js
import { NextResponse } from 'next/server'

export async function GET(request: Request) {
  // 로그인하지 않은 사용자라면, 로그인 페이지로 리다이렉트
  const isLoggedIn = false // 예시용 변수
  if (!isLoggedIn) {
    return NextResponse.redirect(new URL('/login', request.url))
  }
  
  return NextResponse.json({ message: 'Welcome back!' })
}
```

위 코드에서는 사용자가 로그인하지 않았다면 `/login` 경로로 리다이렉트시키고, 로그인되어 있으면 JSON 메시지를 보내줘요.

---

### 추가 팁: HTTP 상태 코드 지정하기

`redirect()`는 기본적으로 307 Temporary Redirect 상태 코드를 사용하는데, 필요에 따라 다른 상태 코드를 지정할 수도 있습니다.

```js
return NextResponse.redirect(new URL('/login', request.url), 302)
```

여기서 `302`는 임시 리다이렉트를 의미해요. 상황에 맞게 301 (영구 리다이렉트) 같은 코드를 넣어도 됩니다.

---

### 정리하자면…

| 기능          | 예시 코드                                      | 설명                                               |
|---------------|------------------------------------------------|----------------------------------------------------|
| JSON 응답     | `NextResponse.json({ key: 'value' }, { status: 200 })` | JSON 데이터와 상태 코드 함께 보내기                   |
| 리다이렉트    | `NextResponse.redirect(new URL('/path', request.url), 302)` | 클라이언트를 다른 URL로 리다이렉트하기                  |

이 두 함수만 잘 활용해도 Next.js 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에서 리다이렉션을 구현할 때는 `NextResponse.redirect()`를 사용하면 정말 편리해요. 간단히 말해, 원하는 URL로 사용자를 보내는 기능인데요, URL을 동적으로 만들거나 수정할 수도 있답니다.

예를 들어, 기본적인 리다이렉트는 이렇게 할 수 있어요:

```js
import { NextResponse } from 'next/server'

export function middleware(request) {
  return NextResponse.redirect(new URL('/new', request.url))
}
```

위 코드는 현재 요청된 URL을 기준으로 `/new` 경로로 사용자를 넘겨주는 동작이에요.

여기서 더 한 걸음 나아가면, 기존 URL 정보도 활용해서 쿼리 파라미터를 붙이는 것도 가능하답니다! 

```js
import { NextResponse } from 'next/server'

export function middleware(request) {
  // 현재 요청 URL을 기준으로 /login 페이지를 만든다
  const loginUrl = new URL('/login', request.url)
  // query parameter로 from=/현재경로 정보를 추가
  loginUrl.searchParams.set('from', request.nextUrl.pathname)
  // 그리고 리다이렉트!
  return NextResponse.redirect(loginUrl)
}
```

이렇게 하면 `/login?from=/현재경로` 형태의 URL로 보내서, 로그인 후 다시 원래 페이지로 돌아가게 하는 UX도 구현할 수 있죠.

---

참고로, `request.nextUrl`은 Next.js가 제공하는 편리한 속성으로, 요청 URL의 구성요소를 쉽게 읽고 수정할 수 있게 도와줘요. 그냥 `request.url`은 문자열인데, `nextUrl`은 URL 객체라서 더 편합니다.

또한, 미들웨어 안에서 리다이렉션을 사용할 때는 항상 올바른 상대경로나 절대경로를 사용해야 하며, 프로토콜이나 도메인이 바뀌는 리다이렉트는 미들웨어 환경에 따라 제한될 수 있으니 주의해주세요.

이런 방식으로 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>

## rewrite() 함수 살펴보기

Next.js에서 `rewrite()` 함수는 원래의 URL은 그대로 유지하면서, 서버 내에서 요청을 다른 경로로 내부 재요청(proxing)할 때 유용해요. 쉽게 말해, 브라우저 주소창에 주소가 그대로 보이는데, 실제로는 다른 URL에서 처리를 하고 싶을 때 사용하죠.

예를 들어, 아래처럼 코드를 작성했다고 가정해볼게요.

```js
import { NextResponse } from 'next/server'

// 사용자가 /about 경로로 요청하지만 내부적으로는 /proxy로 재작성
return NextResponse.rewrite(new URL('/proxy', request.url))
```

- **브라우저 주소창**: `/about` 그대로 유지
- **실제 서버 처리 경로**: `/proxy`

이렇게 하면 URL 구조를 깔끔하게 유지하면서 내부적으로 다른 핸들러나 API 라우트에 요청을 넘길 수 있어요.

---

## next()는 무엇인가요?

`next()`는 미들웨어 체인에서 현재 미들웨어를 종료하고 다음 미들웨어로 제어를 넘겨주는 함수입니다. 만약 경로를 바꿔주지 않고 단순히 현재 요청을 그대로 처리하고 싶다면 `NextResponse.next()`를 호출해요.

예를 들어,

```js
import { NextResponse } from 'next/server'

export function middleware(request) {
  // 특정 조건에서만 재작성하고, 그렇지 않으면 그냥 다음 미들웨어로
  if (request.nextUrl.pathname.startsWith('/proxy')) {
    return NextResponse.rewrite(new URL('/api/proxy', request.url))
  }
  return NextResponse.next()
}
```

위 코드는 `/proxy`로 시작하는 요청은 `/api/proxy`로 내부 요청을 재작성하지만, 그 외의 경로는 그냥 원래 경로대로 처리하라는 의미입니다.

---

### 정리하자면
| 함수            | 역할                                     | 브라우저 주소창 반영 여부       |
| --------------- | ---------------------------------------- | ----------------------- |
| `NextResponse.rewrite()` | 요청 경로를 서버 쪽에서 내부적으로 변경함       | 아니요 (원래 경로 유지)      |
| `NextResponse.next()`    | 다음 미들웨어 또는 원래 처리 로직으로 제어 넘김  | 해당 없음 (경로 변경 없음)   |

---

이 기능 덕분에 깔끔한 URL 설계도 가능하고, 복잡한 리버스 프록시(proxy) 역할도 손쉽게 만들 수 있어요. 특히 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
import { NextResponse } from 'next/server'

return NextResponse.next()
```

그리고 응답을 만들 때 헤더를 그대로 전달하거나, 새로운 헤더를 추가해서 넘길 수도 있어요. 예를 들어, 클라이언트 요청의 헤더를 받아서 수정하거나 필요한 정보를 추가하고 싶을 때 이렇게 하면 됩니다:

```js
import { NextResponse } from 'next/server'

// 들어온 요청을 기준으로 기존 헤더를 복사
const newHeaders = new Headers(request.headers)

// 새 헤더 추가
newHeaders.set('x-version', '123')

// 수정된 헤더를 포함한 다음 단계 응답 반환
return NextResponse.next({
  request: {
    headers: newHeaders,
  },
})
```

헤더를 이렇게 다룰 수 있으면, 인증 토큰이나 사용자 맞춤 정보 등 다양한 데이터를 미들웨어에서 편리하게 관리할 수 있어서 미들웨어 로직 작성이 훨씬 유연해져요!

혹시 next()만 쓰다가 특정 상황에서는 다른 Response 객체를 직접 반환해야 한다면, `NextResponse.rewrite()`나 `NextResponse.redirect()` 같은 메서드들도 함께 알아두면 좋습니다. 이렇게 다양한 Response 객체를 활용하면 미들웨어에서 요청 흐름을 자유롭게 제어할 수 있답니다!

Nextjs 15에서 응답 처리 쉽게 하는 방법(NextResponse)

# ImageResponse 사용법 간단 정리

Next.js의 `ImageResponse`는 JSX와 CSS를 활용해 동적인 이미지를 만들어낼 수 있는 아주 멋진 기능이에요. 특히 소셜미디어용 이미지, 예를 들어 Open Graph 이미지나 트위터 카드 이미지를 자동으로 생성할 때 많이 쓰이죠.

---

## ImageResponse 생성자 옵션

```js
import { ImageResponse } from 'next/og'

new ImageResponse(
  element: ReactElement,
  options: {
    width?: number = 1200, // 이미지 가로 크기 (기본 1200px)
    height?: number = 630, // 이미지 세로 크기 (기본 630px)
    emoji?: 'twemoji' | 'blobmoji' | 'noto' | 'openmoji' = 'twemoji', // 이모지 스타일 선택 가능
    fonts?: {
      name: string,        // 폰트 이름
      data: ArrayBuffer,   // 폰트 데이터 (ArrayBuffer 포맷)
      weight: number,      // 폰트 두께
      style: 'normal' | 'italic' // 폰트 스타일 지정
    }[],
    debug?: boolean = false, // 디버그 모드 활성화 여부

    // HTTP 응답에 쓰일 추가 옵션들
    status?: number = 200,       // HTTP 상태 코드
    statusText?: string,         // 상태 메시지
    headers?: Record<string, string> // 헤더 정보
  },
)
```

---

## 간단 설명

- **element**: JSX 요소를 넘겨주면 그걸로 이미지를 만들어냅니다.
- **width / height**: 생성될 이미지의 크기를 결정합니다. 보통 소셜 미디어용 이미지 사이즈로 1200x630을 많이 사용해요.
- **emoji**: 이모지 스타일을 지정할 수 있어요. 원하는 이모지 스타일을 골라서 좀 더 개성있는 이미지를 만들어보세요.
- **fonts**: 원하는 커스텀 폰트를 불러와서 쓸 수도 있습니다. ArrayBuffer 포맷으로 폰트 데이터를 준비해야 하는데, 웹에서 폰트를 직접 임포트해서 사용하는 것과는 조금 다르니 참고하세요.
- **debug**: 이미지 생성할 때 콘솔이나 에러 정보가 더 많이 보고 싶다면 true로 설정하면 됩니다.
- **status / statusText / headers**: HTTP 응답 설정용. 이미지 API를 만들 때 상태 코드를 따로 지정하거나 헤더를 붙이고 싶을 때 사용해요.

---

## 추가 팁!

- 커스텀 폰트를 적용하려면 미리 폰트를 ArrayBuffer로 변환하는 과정이 필요해요. 예를 들어, `fetch`로 폰트 파일을 받은 뒤 `arrayBuffer()`를 호출해서 준비하면 됩니다.
- 이모지 스타일을 바꾸면 이미지 분위기가 확 달라져서, 브랜딩에 맞게 적용하면 좋아요.
- 디버그 모드를 켜면 어떤 CSS나 요소가 문제인지 더 쉽게 파악할 수 있어서 개발 초반에 유용해요.

---

Next.js에서 동적 이미지 생성하는 게 필요하다면 `ImageResponse` 한 번 꼭 써보세요! 특히 자동으로 OG 이미지를 만들어주는 환경에서는 시간을 엄청 아껴준답니다.


<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>

## 지원하는 CSS 속성들

Satori의 문서를 참고하면 어떤 HTML과 CSS 기능들이 지원되는지 자세히 확인할 수 있어요. 직접 사용해보면서 어떤 스타일들이 잘 먹히는지도 체크해보시면 좋습니다.

## 버전 히스토리

| 버전       | 변경 사항                                                      |
|------------|---------------------------------------------------------------|
| `v14.0.0`  | `ImageResponse`가 `next/server`에서 `next/og`로 이동되었습니다.   |
| `v13.3.0`  | `ImageResponse`를 `next/server`에서 임포트할 수 있게 되었습니다.  |
| `v13.0.0`  | `@vercel/og` 패키지를 통해 `ImageResponse`가 도입되었습니다.       |

요즘 Next.js에서 이미지 관련 기능들이 점점 발전하고 있는데요, 특히 `ImageResponse` 같은 기능은 동적으로 이미지를 생성할 때 굉장히 편리해요. 다만 버전에 따라서 임포트 경로나 패키지가 달라질 수 있으니 사용 전 문서를 한번만 꼭 확인하는 것을 추천합니다. 이 부분을 미리 숙지해두면 버전 업그레이드 시에 불필요한 에러를 줄일 수 있거든요!

Next.js 15에서 ImageResponse를 활용해 이미지 생성 방법

# NextRequest

NextRequest는 기존의 Web Request API를 확장해서 더 편리한 메서드들을 추가한 거예요.

## cookies

Request의 Set-Cookie 헤더를 읽거나 수정할 수 있어요.

---

여기서 NextRequest는 보통 웹에서 HTTP 요청을 다룰 때 기본적으로 제공하는 Request 객체보다 좀 더 쓰기 편하게 기능을 확장한 거라고 생각하면 돼요. 특히 쿠키 같은 걸 다룰 때 번거로운 부분이 있는데, NextRequest는 그런 부분을 깔끔하게 처리해줘서 개발할 때 훨씬 편리하답니다.

예를 들어, 서버에서 특정 쿠키 값을 쉽게 읽거나, 새 쿠키를 설정할 때 도움이 되죠. 서버 사이드 렌더링(SSR)이 많아지는 요즘, 이런 유틸리티가 있으면 작업 속도가 확실히 빨라져요.

쿠키를 직접 다룰 때 주의할 점도 하나 말씀드리자면, 보안 설정(예: HttpOnly, Secure, SameSite 등)을 꼼꼼히 관리해야 해요. NextRequest 같은 툴로 쿠키를 다룰 때도 이런 설정을 신경 써줘야 보안 사고를 미연에 방지할 수 있으니 참고하세요!


<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>

### set(name, value)

이 함수는 특정 이름(name)과 값(value)을 받아서 요청(request)에 해당하는 쿠키를 설정해줘요.

예를 들어, 사용자가 `/home` 페이지에 들어왔을 때 배너를 숨기고 싶다면 이렇게 작성할 수 있죠:

```js
// /home 페이지에 들어온 요청에서
// 'show-banner'라는 쿠키를 'false'로 설정해서 배너를 숨겨요
// 이 요청은 'Set-Cookie: show-banner=false; path=/home' 헤더를 가지게 돼요
request.cookies.set('show-banner', 'false')
```

즉, 브라우저가 다음 번에 `/home` 경로에 요청을 보낼 때 `show-banner=false`라는 쿠키를 함께 보내게 됩니다.

---

### get(name)

다음으로 `get(name)`은 설정된 쿠키 중에서 특정 이름을 가진 쿠키의 값을 가져오는 함수예요.

```js
// 예를 들어 쿠키 중 'show-banner'의 값을 가져와서
// 그 값에 따라 배너를 보이거나 숨길 수 있어요
const bannerStatus = request.cookies.get('show-banner')
if (bannerStatus === 'false') {
  // 배너 숨기기 로직
} else {
  // 배너 보여주기 로직
}
```

이렇게 `get`을 사용하면 쿠키에 저장된 상태 정보를 쉽게 읽어서 사용자 경험을 맞춤화할 수 있답니다.

---

쿠키를 다룰 때는 보안도 중요해요! 예를 들어,

- **HttpOnly** 속성을 사용하는 경우 자바스크립트에서는 쿠키를 읽지 못하도록 할 수 있어요.
- **Secure** 속성을 추가하면 HTTPS 연결에서만 쿠키가 전송돼요.
- **SameSite** 옵션으로 다른 사이트에서 쿠키를 보내는 걸 제한할 수도 있고요.

이런 옵션들도 필요에 따라 같이 설정하는 게 좋아요.

쿠키를 효과적으로 활용해서 사용자 경험을 개선해보세요!


<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>

쿠키 관련 작업을 할 때, 특정 쿠키의 값을 가져오거나 모든 쿠키를 확인하고 싶을 때가 많죠. 여기서는 두 가지 유용한 메서드에 대해 이야기해볼게요: `get()`과 `getAll()`입니다.

### get(cookieName)

- 주어진 쿠키 이름에 해당하는 쿠키 값을 반환해요.
- 만약 동일한 이름의 쿠키가 여러 개 있으면, 가장 먼저 찾은 쿠키 값을 반환합니다.
- 쿠키가 없으면 `undefined`를 반환해요.

예시를 들어볼게요.

```js
// 요청이 /home 경로로 들어왔다고 가정
// 쿠키 중에 { name: 'show-banner', value: 'false', Path: '/home' } 가 있다고 할 때
const bannerValue = request.cookies.get('show-banner');
console.log(bannerValue); // 'false'
```

여기서 기억할 점은, 도메인이나 경로와 같은 쿠키 속성 때문에 같은 이름의 쿠키가 여러 개 존재할 수 있다는 거예요. `get()`은 처음 발견한 값만 준다는 점도 참고하세요.

---

### getAll(cookieName)

- 특정 쿠키 이름을 주면, 그 이름을 가진 **모든** 쿠키 값을 배열로 반환합니다.
- 만약 이름 없이 호출하면, 요청에 포함된 모든 쿠키를 반환해요.

예를 들어:

```js
// 예를 들어 여러 개의 'theme' 쿠키가 있을 수 있어요
const themes = request.cookies.getAll('theme');
console.log(themes); // ['dark', 'light']

// 이름 없이 호출하면 모든 쿠키를 배열로 받아요
const allCookies = request.cookies.getAll();
console.log(allCookies);
// [ { name: 'show-banner', value: 'false' }, { name: 'theme', value: 'dark' }, ... ]
```

---

### 팁!

- 쿠키 이름은 보통 유니크해야 하지만, Path나 Domain 때문에 중복 있을 수 있어요. 그래서 꼭 필요할 때 `getAll()`을 이용해 여러 쿠키 값을 한 번에 알아보면 유용합니다.
- 쿠키 값은 문자열로 전달되니, JSON 형태 같은 데이터를 저장할 땐 `JSON.stringify`와 `JSON.parse`를 꼭 활용하세요.

---

이렇게 `get()`과 `getAll()`만 잘 활용해도 쿠키를 다루는 데 훨씬 편해질 거예요! 도움이 되셨나요? 궁금한 점 있으면 언제든 질문 주세요~


<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>

자, 오늘은 JavaScript에서 요청(request) 객체 내 쿠키를 다루는 방법에 대해 살펴볼게요. 쿠키를 읽고, 여러 개를 가져오고, 삭제하는 방법까지 간단하게 정리해볼게요.

---

### 쿠키 여러 개 가져오기

요청에 담긴 쿠키가 여러 개일 때 특정 이름을 가진 쿠키들 또는 모든 쿠키들을 가져오고 싶을 때가 있죠? `request.cookies.getAll()` 메서드를 사용하면 돼요.

```js
// 예를 들어 /home 경로에 이런 쿠키가 있을 때
[
  { name: 'experiments', value: 'new-pricing-page', Path: '/home' },
  { name: 'experiments', value: 'winter-launch', Path: '/home' },
]

// 특정 이름 'experiments' 쿠키 모두 가져오기
request.cookies.getAll('experiments')

// 아니면 그냥 모든 쿠키 가져오기
request.cookies.getAll()
```

이렇게 하면 해당 이름을 가진 모든 쿠키값 배열을 받을 수 있어서, 실험 기능 활성화 여부 등을 여러 개 동시 관리할 때 유용해요.

---

### 쿠키 삭제하기

쿠키를 없애고 싶을 때는 `delete(name)` 메서드를 사용하면 됩니다. 삭제 성공 여부도 boolean 형태로 알려줘서 관리하기 좋아요.

```js
// 'experiments' 쿠키를 삭제하려고 시도
const deleted = request.cookies.delete('experiments')
if(deleted) {
  console.log('쿠키가 정상적으로 삭제됐어요!')
} else {
  console.log('해당 이름의 쿠키가 없어서 삭제하지 못했어요.')
}
```

여기서 주의할 점! 쿠키 삭제는 클라이언트에서 관리되는 쿠키를 서버 사이드에서 다룰 때 잘 동작하는 경우가 많으니, 프론트엔드와 백엔드 쿠키 경로와 옵션이 일치하는지 확인하는 게 좋아요.

---

### 추가 팁: 쿠키 관리 시 체크할 점

- 쿠키 이름은 중복될 수 있으니 `getAll()`로 모두 가져오고 원하는 것을 필터링하는 게 안전합니다.
- `Path`, `Domain` 같은 속성이 다르면 동일 이름 쿠키 복수 존재 가능하니, 특정 경로나 조건을 꼭 확인하세요.
- 보안 설정(`HttpOnly`, `Secure`) 때문에 클라이언트에서 못 읽는 쿠키도 있으니 상황에 따라 백엔드에서만 처리할 수도 있답니다.

---

쿠키는 사용자 경험을 향상시키기 위한 중요한 도구인데요, 이렇게 JavaScript에서 요청 내 쿠키를 자유자재로 불러오고, 삭제할 수 있으면 훨씬 유연한 웹 서비스 운영이 가능해져요! 필요할 때 바로 꺼내 쓰는 방법, 오늘 꼭 알아가세요~


<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>

### has(name)

`has(name)`는 요청(request) 안에 특정 이름의 쿠키가 있는지 확인할 때 사용해요. 만약 해당 이름의 쿠키가 있으면 `true`를, 없으면 `false`를 반환하죠.

```js
// 'experiments'라는 이름의 쿠키가 요청에 있으면 true, 없으면 false 반환
request.cookies.has('experiments')
```

예를 들어 사용자 인증이나 실험 기능 토글 같은 상황에서 쿠키 존재 여부를 확인할 때 유용해요.

---

### clear()

`clear()` 메서드는 요청에 포함된 모든 쿠키를 한 번에 삭제해버릴 때 사용해요. 

이걸 쓰면 브라우저에 저장된 쿠키가 싹 사라지는 건 아니고, 현재 요청에서 다루는 쿠키 세트를 비우는 효과라고 보면 됩니다. 서버에서 받은 요청과 관련된 쿠키 데이터를 초기화할 때 좋죠.

---

#### 참고로!

쿠키는 HTTP 요청/응답의 중요한 부분이라서, 프론트엔드든 백엔드든 잘 다뤄야 해요. 예를 들어 보안 목적으로 HttpOnly, Secure, SameSite 속성을 잘 설정하거나, 쿠키 저장 용량과 만료 시간도 신경 써야 하죠.

마크다운에서 표로 쿠키 관련 주요 메서드 간단히 정리해봤어요.

| 메서드          | 설명                                          | 반환값            |
|-----------------|----------------------------------------------|-------------------|
| `has(name)`     | 요청에 특정 이름의 쿠키가 있는지 확인        | `true` or `false` |
| `clear()`       | 요청에 포함된 모든 쿠키 정보를 초기화         | 없음              |

이렇게 쿠키는 사용법이 간단해 보여도, 프로젝트에 따라 꼭 필요한 보안과 정책을 꼼꼼히 챙기는 게 중요해요!


<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>

요청(request)에서 Set-Cookie 헤더를 제거하고 싶을 때, 보통 클라이언트 측에서는 Set-Cookie를 직접 수정할 수 없어요. 왜냐하면 Set-Cookie는 서버에서 응답(response)에 포함하는 헤더라서, 요청(request)에서는 일반적으로 존재하지 않거든요.

하지만, 만약 요청에 포함된 쿠키들을 깔끔하게 초기화하거나 지우고 싶다면, `request.cookies.clear()` 같은 메서드를 사용할 수 있어요. 이 방법은 Next.js 13에서 도입된 새로운 서버 컴포넌트 혹은 API Route 핸들링에서 사용되는 쿠키 객체에 적용되는 방식입니다.

정리하면,

| 작업                  | 설명                                      |
|----------------------|-----------------------------------------|
| `request.cookies.clear()` | 요청에 포함된 모든 쿠키들을 지웁니다.           |
| Set-Cookie 헤더 변경     | Set-Cookie 헤더는 서버가 응답 시 설정하는 쿠키이므로, 요청에서 직접 제거 불가 |

또한, `nextUrl` 객체는 기본 URL API를 확장한 것으로, Next.js에서 유용하게 쓸 수 있는 여러 확장 기능이 포함되어 있어요. 예를 들어 URL의 쿼리 파라미터를 쉽게 다루거나, Next.js 라우팅에 특화된 프로퍼티들이 있죠.

간단하게 사용 예시를 보여드리자면:

```js
export function middleware(request) {
  console.log(request.nextUrl.pathname) // 현재 요청 경로
  request.cookies.clear() // 쿠키 초기화
}
```

참고로, `request.cookies`는 immutable 한 객체라서 바로 수정이 안 될 수도 있는데, Next.js에서는 이 부분을 직접 제어할 수 있도록 API를 제공합니다. 요청 쿠키를 다뤄야 할 때는 꼭 Next.js 문서를 참고해서 정확한 방법을 확인하는 것이 좋아요.

필요하시면 더 자세한 쿠키 다루기 방법이나 `nextUrl` 활용법도 알려드릴게요!


<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>

```js
// /home 경로로 요청 시 pathname은 /home
request.nextUrl.pathname
// /home?name=lee 로 요청 시 searchParams는 { 'name': 'lee' }
request.nextUrl.searchParams
```

아래는 `request.nextUrl`에서 사용할 수 있는 주요 옵션들입니다:

| 속성           | 타입                     | 설명                                                                                  |
| -------------- | ------------------------ | ------------------------------------------------------------------------------------- |
| `basePath`     | `string`                 | URL의 [base path](https://nextjs.org/docs/app/api-reference/config/next-config-js/basePath)입니다.                     |
| `buildId`      | `string` \| `undefined`  | Next.js 앱의 빌드 식별자입니다. [커스터마이징](https://nextjs.org/docs/app/api-reference/config/next-config-js/generateBuildId)도 가능합니다. |
| `pathname`     | `string`                 | URL의 경로 부분입니다.                                                                |
| `searchParams` | `Object`                 | URL의 쿼리 파라미터들을 담고 있는 객체입니다.                                         |

> 참고) 페이지 라우터(Pages Router)에서 제공하던 국제화(i18n) 관련 속성들은 앱 라우터(App Router)에서는 사용할 수 없으니 참고하세요. 앱 라우터에서의 국제화는 [앱 라우터 문서](https://nextjs.org/docs/app/building-your-application/routing/internationalization)에서 더 자세히 확인할 수 있습니다.

---

덧붙이자면, `request.nextUrl.searchParams` 는 `URLSearchParams` 인터페이스를 기반으로 하므로, `.get()`, `.has()`, `.getAll()` 같은 메서드를 통해 쿼리 파라미터를 손쉽게 다룰 수 있다는 장점이 있어요. 예를 들어:

```js
const name = request.nextUrl.searchParams.get('name')
```

이렇게 하면 쿼리에서 'name' 값만 간단히 얻을 수 있으니 참고하세요! 😊


<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` | `ip`와 `geo` 기능이 제거됨 |

---

여기서 `ip`와 `geo`가 뭔지 궁금할 수 있는데요, 보통 `ip`는 IP 주소 관련 기능, `geo`는 지리 정보 관련 기능을 뜻해요. 그래서 이번 버전(v15.0.0)부터는 이 두 가지 기능이 빠졌다는 뜻이죠. 만약 프로젝트에서 IP나 위치 기반 기능을 쓴다면, 이번 업데이트 전후로 영향이 있는지 꼭 확인해보는 게 좋아요! 업데이트 후에는 이 기능들을 대신할 다른 라이브러리나 API를 찾아보는 것도 방법일 수 있겠네요.

Posts