# template.js 파일 이해하기

이번에는 `template.js` 파일에 대해 이야기해볼게요. 템플릿 파일은 레이아웃(layout)과 비슷한 역할을 하지만, 조금 다릅니다.

레이아웃은 여러 라우트(route)에서 유지되면서 상태(state)를 유지하는 반면, 템플릿은 고유한 키(unique key)를 가지고 있어서 자식 클라이언트 컴포넌트(Client Components)의 상태가 페이지가 이동할 때마다 초기화(reset)된다는 차이가 있어요.

예를 들어, 다음과 같은 템플릿 컴포넌트가 있다고 가정해볼게요.

```js
export default function Template({ children }: { children: React.ReactNode }) {
  return <div>{children}</div>;
}
```

이 코드에서는 `children`을 받아서 `<div>`로 감싸기만 했죠. 이 템플릿을 사용하면, 페이지를 이동할 때마다 자식 컴포넌트들의 상태가 초기화됩니다.

---

### 상태 유지 vs 초기화: 왜 중요할까?

- **레이아웃**은 여러 페이지 사이를 오가더라도 상태가 유지돼요. 예를 들어, 사이드바가 열려있는 상태를 유지하고 싶다면 레이아웃이 맞아요.
- **템플릿**은 페이지 또는 특정 라우트마다 상태를 초기화해야 할 때 씁니다. 예를 들어, 폼 입력값을 페이지별로 완전히 새로 시작하고 싶을 때요.

---

### 꿀팁: 템플릿과 레이아웃, 언제 써야 할까?

- 상태 유지가 필요하면 → 레이아웃을 사용하세요.
- 상태 초기화가 필요하면 → 템플릿을 사용하세요.

i이해를 돕기 위해 이미지도 참고하면 좋아요!
t
![template 개념 이미지](/TIL/assets/img/2025-04-22-templatejs_0.png)

---

요약하자면, `template.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>

가끔은 레이아웃(Layout) 대신에 템플릿(Template)을 선택하는 게 더 나은 경우도 있어요. 예를 들면:

- useEffect (예: 페이지 뷰 로깅)나 useState (예: 각 페이지별 피드백 폼) 같은 훅을 활용하는 기능이 필요할 때.
- 기본 프레임워크 동작 방식을 바꾸고 싶을 때. 예를 들어, 레이아웃 내의 Suspense 경계는 레이아웃이 처음 로드될 때만 fallback UI를 보여주고 페이지 전환 시에는 보여주지 않지만, 템플릿에서는 페이지가 바뀔 때마다 fallback UI가 매번 표시됩니다.

## Props

### children (필수)

children은 템플릿 내부에 렌더링될 자식 요소들을 의미합니다. 이걸 사용해서 부모 컴포넌트에서 자식 컴포넌트를 감싸거나 그 안에 배치할 수 있어요. React에서 자식 요소를 다룰 때 거의 항상 사용하니까 꼭 기억해두세요!

---

추가로, 레이아웃과 템플릿 선택 기준에 대해 조금 더 설명하자면, 레이아웃은 기본적으로 페이지 전환 시 지속되는 공통 UI나 구조를 만드는 데 쓰이고, 템플릿은 각 페이지가 로드될 때마다 새로 렌더링되어야 하는 동적인 UI나 상태 관리가 필요할 때 적합해요. 개발하는 서비스의 특성과 UX 목표에 따라 적절히 선택하면 됩니다!



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

Template 컴포넌트는 children prop을 받아 사용할 수 있어요. 예를 들어 이렇게 작성할 수 있죠:

```jsx
<Layout>
  {/* 템플릿에는 자동으로 고유한 key가 주어진다는 점 참고하세요. */}
  <Template key={routeParam}>{children}</Template>
</Layout>
```

> 알아두면 좋은 점:
> 기본적으로 템플릿은 서버 컴포넌트(Server Component)로 동작하지만, "use client" 지시어를 붙이면 클라이언트 컴포넌트(Client Component)로도 사용할 수 있습니다.
> 사용자가 템플릿을 공유하는 여러 라우트 사이를 이동할 때는 컴포넌트가 새로 마운트되고, DOM 요소들도 재생성돼요. 그래서 클라이언트 컴포넌트의 상태는 유지되지 않고, effect도 다시 실행됩니다.

즉, 템플릿을 클라이언트 측에서 사용한다면 상태 관리 혹은 사이드 이펙트 처리에 유의해야 한다는 점 기억하세요!

## Version History

(이후 버전 히스토리 내용이 이어지는 부분이라면 여기에 추가 정보를 넣을 수 있어요.)



<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                |
| --------- | ---------------------- |
| `v13.0.0` | `template` introduced. |

여기서 'template'이 새로 도입되었다고 하네요. 보통 이런 변경 사항은 라이브러리나 프레임워크의 중요한 기능 추가나 개선일 가능성이 높아요. 만약 여러분이 사용 중인 버전이 13.0.0이라면 이 'template' 기능을 꼭 한번 살펴보는 걸 추천해요. 새로운 기능이 어떤 식으로 코드를 더 깔끔하게 해주거나, 생산성을 높여줄지 직접 써보면서 경험해보는 게 가장 좋아요!

nextjs 15에서 template.js 사용하는 방법

# unauthorized.js

`unauthorized.js` 파일은 인증 과정에서 `unauthorized` 함수가 호출될 때 보여줄 UI를 렌더링하는 역할을 해요. 이 파일을 통해 UI를 원하는 대로 꾸밀 수 있을 뿐만 아니라, Next.js가 자동으로 401 상태 코드를 반환해 준답니다.

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

export default function Unauthorized() {
  return (
    <main>
      <h1>401 - Unauthorized</h1>
      <p>Please log in to access this page.</p>
      <Login />
    </main>
  )
}
```

위 코드를 보면, 기본적으로 "401 - Unauthorized"라는 제목과 함께 로그인을 요청하는 문구가 보이고, `Login` 컴포넌트를 렌더링해 실제 로그인 화면도 함께 표시하고 있어요.

### 조금 더 알아보기

- **401 상태 코드란?**  
  401은 '인증이 필요함'을 나타내는 HTTP 상태 코드로, 사용자가 인증되지 않은 상태에서 접근 권한이 필요한 페이지에 접근할 때 서버가 보내요.

- **Next.js에서의 활용 팁**  
  이 파일을 커스터마이징하면 에러 페이지를 여러분의 서비스 스타일에 맞게 꾸밀 수 있답니다. 예를 들어, 로그인 버튼 대신 소셜 로그인이나 회원가입으로 유도하는 링크도 넣어볼 수 있겠죠?

- **추가로 하면 좋은 것**  
  사용자가 왜 인증이 필요한지 좀 더 자세한 안내나, 인증 절차에 도움이 될 만한 FAQ 링크를 같이 넣으면 UX가 더 좋아질 수 있어요.

필요하면 한 번 직접 만들어보고, 여러분만의 인증 오류 페이지도 멋지게 만들어 보세요!


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

### Props

`unauthorized.js` 컴포넌트는 어떤 props도 받지 않습니다.

## 예시

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

로그인하지 않은 사용자를 대상으로 로그인 화면을 보여주고 싶을 때, `unauthorized.js` 컴포넌트를 사용할 수 있어요. 참고로 이 컴포넌트는 추가 설정을 위해 props를 받지 않으니, 간단하게 기본 UI를 렌더링하는 용도로 쓴다는 점 기억하세요.

만약 내 서비스에서 로그인 여부에 따라 다른 화면을 보여줘야 한다면, 조건문으로 이 컴포넌트를 넣어주면 됩니다. 예를 들어:

```jsx
{ !userIsLoggedIn && <Unauthorized /> }
```

이렇게 하면 인증되지 않은 사용자에게만 로그인 페이지가 표시되고, 이미 로그인한 사용자에겐 다른 화면이 보여지겠죠?

추가로, `unauthorized.js` 컴포넌트 내부를 수정해 나만의 로그인 UI로 커스터마이징해도 좋습니다. 그럴 땐 props 대신 내부 상태나 리덕스 등 상태관리 라이브러리를 이용해서 유연하게 UX를 조절해보세요!


<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' 함수를 이용해 인증되지 않은 사용자에게 로그인 UI를 보여주는 방법을 쉽게 설명해드릴게요.

먼저, `DashboardPage` 컴포넌트를 살펴봅시다. 여기서는 `verifySession()` 함수를 통해 사용자의 세션 정보를 확인하는데요, 이 함수는 비동기 함수라 `await`를 붙여 호출해주고 있어요.

```jsx
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()` 함수가 null 또는 undefined를 반환한다면 세션이 없는 것으로 간주하고, `unauthorized()` 함수를 호출해버립니다.
- 이 `unauthorized()` 함수는 내부적으로 Next.js에 내장된 기능으로, 렌더링을 멈추고 `unauthorized.js` 파일을 호출해서 401 페이지를 보여주게 해줍니다.

그럼 그 `unauthorized.js` 파일에 어떤 컴포넌트가 있냐면,

```jsx
import Login from '@/app/components/Login'
 
export default function UnauthorizedPage() {
  return (
    <main>
      <h1>401 - Unauthorized</h1>
      <p>Please log in to access this page.</p>
      <Login />
    </main>
  )
}
```

이렇게 간단하게 로그인 UI를 포함한 페이지를 만들고 있어요. 화면에 “401 - Unauthorized” 메시지와 로그인 폼이 나타나게 되는 거죠.

---

### 한 번에 쉽게 인증 처리하기

사실 여기서 중요한 점은, 이런 패턴을 쓰면 페이지 보호 로직이 깔끔해진다는 거예요. 개발자 입장에서 보면, 사용자가 로그인을 하지 않은 상태면 바로 401 페이지로 분기시키고, 그 화면에서 자연스럽게 로그인하도록 유도할 수 있죠.

- 기존의 리다이렉트 방식이나, 클라이언트 사이드에서 상태를 확인하는 것보다 서버에서 바로 인증 상태를 확인하는 게 보안상 더 안전합니다.
- 물론 세션 검증 함수(`verifySession`)는 직접 구현해야 해요. 예를 들어 쿠키에 포함된 토큰을 해석하거나, 데이터베이스를 조회해서 유효성을 검사하게 됩니다.

---

### 이해를 돕는 간단 다이어그램

| 동작 단계             | 설명                                    |
|-------------------|---------------------------------------|
| 1. 세션 확인          | `verifySession` 호출해서 로그인 여부 확인          |
| 2. 미인증 사용자 감지     | 세션이 없으면 `unauthorized()` 호출해서 401 페이지 렌더링   |
| 3. 401 페이지 렌더링      | `unauthorized.js`에 정의된 로그인 화면을 보여줌            |
| 4. 로그인 후 세션 생성     | 로그인 컴포넌트에서 정상 로그인이 되면 세션이 생성됨         |
| 5. 접근 허용           | 이후 대시보드 페이지 접속 가능                           |

---

### 마치며

Next.js 앱에서 인증이 필요한 페이지를 다룰 때, ‘unauthorized’ 함수를 잘 활용하면 간단하고 체계적인 접근 제어를 구현할 수 있습니다. 보안도 높이고 UX도 좋으니 여러분께서도 꼭 한 번 써보시길 추천드려요.

추가로, 로그인 컴포넌트나 세션 검증 로직에 대해 궁금하신 점 있으면 댓글로 알려주세요. 다음에는 그 부분도 자세히 다뤄보겠습니다!

오늘도 즐거운 개발 되시길! 🚀


<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.js` 도입됨 |

이번에 `v15.1.0` 버전에서 `unauthorized.js`라는 파일이 새롭게 추가됐어요. 보통 이런 파일 이름은 '허가되지 않은 접근'과 관련된 기능을 처리할 때 쓰이는데요, 예를 들어 로그인이 필요한 페이지에 비로그인 사용자가 접근하려 할 때 보여주는 에러 처리나 리다이렉트 등을 담당할 수도 있답니다.

이렇게 특정 상황에 맞는 자바스크립트 파일을 분리해서 관리하면 코드 유지보수도 편해지고, 필요한 경우에만 로드해서 성능 최적화도 할 수 있어요. 나중에 관련 기능을 더 자세히 살펴볼 기회가 있으면, `unauthorized.js`가 실제로 어떤 역할을 하는지 한번 분석해보는 것도 재밌겠네요!

Next.js 15에서 Unauthorized.js로 권한 없는 접근 처리하는 방법

Next.js 15 라우트 세그먼트 설정 방법과 활용팁

# route.js

Route Handlers는 특정 경로(route)에 대해 커스텀 요청 처리기를 만들 수 있게 해주는 기능이에요. 즉, 내가 원하는 경로에 맞춰서 요청(Request)과 응답(Response)을 직접 다룰 수 있게 해주죠. 이때 Web Request와 Response API를 활용해요.

예를 들어, 아래처럼 GET 요청을 받았을 때 JSON 형태로 간단한 메시지를 응답하는 코드를 작성할 수 있어요:

```js
export async function GET() {
  return Response.json({ message: 'Hello World' });
}
```

이 코드는 "/route" 같은 경로로 GET 요청이 들어오면 `{ message: 'Hello World' }`라는 JSON 데이터를 클라이언트에게 보내주는 역할을 해요. 

추가로 알아두면 좋은 점 몇 가지 알려드릴게요!

- **Method별 함수 지원**: GET뿐 아니라 POST, PUT, DELETE 등 HTTP 메서드에 맞춰서 함수들을 만들 수 있어요.  
- **내장 Response 객체 활용**: 위 예시처럼 `Response.json()` 메서드는 JSON 응답을 쉽게 만들어 주기 때문에 정말 편리해요.
- **비동기 처리 가능**: 데이터베이스 조회나 외부 API 호출처럼 비동기가 필요한 작업도 `async/await` 패턴으로 자연스럽게 처리할 수 있어요.
- **라우팅과 별개로 작동**: Next.js 같은 프레임워크에서는 보통 페이지 라우팅과 별개로 API 응답을 여기서 따로 관리할 수 있답니다!

만약 좀 더 복잡한 요청 처리(예: 요청 본문 읽기, 헤더 조작 등)를 하고 싶다면, Request 객체를 받아 쓰면 됩니다. 예를 들어:

```js
export async function POST(request) {
  const body = await request.json();
  return Response.json({ youSent: body });
}
```

이렇게 하면 클라이언트가 보낸 데이터를 받아서 다시 돌려주는 간단한 POST 처리도 가능해요.

---

## 참고 자료

- 공식 MDN 문서 - [Web Request and Response APIs](https://developer.mozilla.org/en-US/docs/Web/API/Request)
- Next.js API Routes 공식 문서 (비슷한 개념으로 활용 가능)  
- Response 객체 관련 문서: JSON 응답 생성 등 다양한 메서드 지원

---

간단하지만 강력한 route.js의 Route Handlers, 여러분의 서버 로직 구현에 꼭 활용해보세요!


<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 메서드

라우트 파일에서는 특정 경로(route)에 대해 커스텀 요청 핸들러를 만들 수 있어요. 즉, 클라이언트가 어떤 요청을 했는지에 따라 다르게 동작하도록 코드를 작성할 수 있다는 뜻이죠. 여기서 지원하는 HTTP 메서드는 GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS 이렇게 총 7가지에요.

```js
export async function GET(request: Request) {}
 
export async function HEAD(request: Request) {}
 
export async function POST(request: Request) {}
 
export async function PUT(request: Request) {}
 
export async function DELETE(request: Request) {}
 
export async function PATCH(request: Request) {}
 
// 만약 `OPTIONS` 메서드를 직접 정의하지 않으면,
// Next.js가 자동으로 `OPTIONS` 메서드를 구현해주고,
// Route Handler에 정의된 다른 메서드들을 기준으로 `Allow` 헤더를 설정해줍니다.
export async function OPTIONS(request: Request) {}
```

각 함수는 `Request` 객체를 받아서 비동기적으로 처리할 수 있는 함수예요. `Request` 객체를 통해 요청과 관련된 다양한 정보를 얻을 수 있답니다.

#### 간단히 정리한 HTTP 메서드 역할

| 메서드 | 설명 |
|---|---|
| GET | 서버에서 데이터를 읽어올 때 사용해요. 가장 기본적인 요청이죠. |
| POST | 서버에 데이터를 새로 생성할 때 쓰여요. 예를 들어 회원가입 같은 요청이죠. |
| PUT | 데이터를 통째로 수정할 때 사용해요. 기존 데이터를 전부 교체할 때 유용합니다. |
| PATCH | 데이터의 일부만 수정할 때 사용해요. 수정할 부분만 보내면 되어서 효율적이죠. |
| DELETE | 서버에서 데이터를 삭제할 때 쓰여요. |
| HEAD | GET 요청과 비슷하지만 응답 본문(body)은 안 내려줘서 응답 헤더만 받고 싶을 때 유용해요. |
| OPTIONS | 클라이언트가 해당 경로에서 어떤 메서드를 사용할 수 있는지 미리 물어볼 때 사용합니다. |

> **팁!** 실제 API 설계할 때는 각 메서드가 어떤 동작을 하는지 명확하게 구분해서 사용하는 게 좋아요. 그래야 클라이언트가 어떤 요청을 보내야 할지 헷갈리지 않고, 유지보수도 훨씬 쉬워집니다.

다음에는 `Parameters`(매개변수) 부분에 대해 자세히 알아볼게요!


<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에서 NextRequest 활용하기 (feat. request 객체 이해하기)

Next.js에서 API 라우트나 미들웨어를 만들 때, `request` 객체를 자주 다루게 되죠. 그런데 그냥 기본 Web Request API와는 조금 다른, Next.js만의 확장판인 `NextRequest`라는 객체가 있다고 해요.

#### NextRequest란?

`NextRequest`는 기본 Web Request 객체를 상속해서, 더 쉽고 편하게 쓸 수 있게 만든 Next.js 전용 객체입니다. 예를 들어, 쿠키를 꺼내거나, URL 정보를 다룰 때 훨씬 직관적이고 편리해요. `nextUrl`이라는 확장된 URL 객체가 포함되어 있어서, 이걸 활용하면 URL 조작도 손쉽답니다.

#### 간단한 예제

```ts
import type { NextRequest } from 'next/server'

export async function GET(request: NextRequest) {
  // nextUrl을 통해 URL을 쉽게 접근 가능
  const url = request.nextUrl

  // 예: 쿼리 파라미터 출력해보기
  console.log(url.searchParams.get('id'))

  return new Response('Hello World')
}
```

위 코드에서 `request.nextUrl`을 이용하면 URL 전체를 분석할 수 있고, `searchParams`로 쿼리도 쉽게 읽을 수 있어요. 만약 그냥 `request.url`을 쓰면 문자열 형태라, 직접 파싱을 해야 하니까 귀찮죠.

#### NextRequest만의 꿀팁!

- **쿠키 꺼내기**: `request.cookies.get('cookieName')`으로 바로 쿠키 값 꺼낼 수 있어요.
- **헤더 접근**: `request.headers.get('headerName')` 작성법은 동일하지만, 실제로 다루기 더 깔끔해요.
- **POST Body 읽기**: 비동기로 `request.json()` 같은 메서드를 사용해 JSON 본문을 바로 파싱할 수 있습니다.

#### 마무리

Next.js 13부터 등장한 이 `NextRequest` 객체는 서버 컴포넌트나 API 라우트, 미들웨어를 작성할 때 훨씬 편리하고 강력한 도구입니다. 기존의 Web Request 객체보다 기능이 많고, 특히 URL이나 쿠키 처리에 도움을 주니 꼭 활용해 보세요!

궁금하면 Next.js 공식 문서에서 [`NextRequest`](https://nextjs.org/docs/api-reference/edge-runtime#nextrequest)도 참고해보시면 좋습니다.

---

필요하다면 다음에는 `NextResponse` 활용법도 소개할게요. 이걸로 응답을 쉽게 제어할 수 있답니다!


<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의 동적 라우트에서 `params`가 어떻게 사용되는지 보여주는 코드 예제입니다. 이 때 `params`는 현재 라우트의 동적 경로 파라미터들을 담은 객체를 비동기적으로 반환하는 Promise입니다.

```js
export async function GET(
  request: Request,
  { params }: { params: Promise<{ team: string }> }
) {
  const { team } = await params
  // 이제 team 변수에 URL에서 전달된 동적 경로 파라미터가 들어있어요.
}
```

예를 들어, 다음과 같은 라우트 구조와 URL 요청이 있을 때 `params`는 이렇게 들어옵니다:

| Example                        | URL           | params                             |
|-------------------------------|---------------|----------------------------------|
| `app/dashboard/[team]/route.js` | `/dashboard/1` | `Promise<{ team: '1' }>`          |
| `app/shop/[tag]/[item]/route.js` | `/shop/1/2`   | `Promise<{ tag: '1', item: '2' }>` |
| `app/blog/[...slug]/route.js`    | `/blog/1/2`   | `Promise<{ slug: ['1', '2'] }>`    |

여기서 `[team]`, `[tag]`, `[item]` 같은 부분이 동적 경로 파라미터를 나타내고, `[...,slug]`는 여러 경로 세그먼트를 배열 형태로 받을 때 사용합니다.

### 덧붙여서

- `params`가 Promise인 이유는 Next.js가 라우트의 데이터 패칭 시점에 비동기 처리를 하기 때문이에요. 그래서 항상 `await`을 사용해 값을 꺼내주어야 해요.
- 동적 라우트를 사용할 땐, `params`에서 기대하는 속성명이 URL 안 동적 경로 이름과 정확히 일치하는지 꼭 확인해야 합니다.
- 여러 개의 동적 파라미터가 있다면, 그 만큼 프로퍼티를 비동기로 받아서 처리할 수 있어요.  
- 다중 세그먼트 캡쳐(`[...slug]`)는 블로그 포스트나 검색 결과처럼 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>

### 쿠키 다루기

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

export async function GET(request: NextRequest) {
  const cookieStore = await cookies()

  const a = cookieStore.get('a')       // 쿠키 'a' 값을 가져오기
  const b = cookieStore.set('b', '1')  // 쿠키 'b'를 '1'로 설정하기
  const c = cookieStore.delete('c')    // 쿠키 'c' 삭제하기
}
```

Next.js의 `cookies()` 함수로 쉽게 쿠키를 가져오고 설정하고 삭제할 수 있어요. 여기서 중요한 건 `cookies()`가 비동기 함수라는 점인데, 그래서 `await`를 붙여줘야 제대로 값을 받을 수 있답니다.

`cookieStore.get()`은 해당 이름의 쿠키 정보를 객체 형태로 줘요. 없으면 `undefined`를 반환하고요. `cookieStore.set()`은 새로운 쿠키를 추가하거나 기존 쿠키를 덮어씁니다. `cookieStore.delete()`는 지정한 쿠키를 삭제할 때 씁니다.

클라이언트와 서버 모두 쿠키를 다루지만, Next.js API Route 혹은 Route Handler에서는 이렇게 `next/headers`에서 제공하는 함수를 활용하면 훨씬 간단해져서 좋아요!

---

## 버전 히스토리

| Version         | Changes                                                                  |
|-----------------|--------------------------------------------------------------------------|
| `v15.0.0-RC`    | `context.params`가 이제 프로미스 형태로 바뀌었어요. [codemod](https://nextjs.org/docs/app/guides/upgrading/codemods#150) 도 제공됩니다. |
| `v15.0.0-RC`    | `GET` 핸들러의 기본 캐싱 정책이 static에서 dynamic으로 변경됐습니다.          |
| `v13.2.0`       | Route Handlers가 처음 소개되었습니다.                                     |

Next.js는 계속 발전 중이라 버전마다 큰 변화가 있는데, 특히 Route Handler와 쿠키, 캐시 다루는 방식도 바뀌니 공식 문서를 챙겨보시는 걸 추천해요! 혹시 기존 코드를 15버전 이상으로 올리려면 codemod를 꼭 활용해보세요. 작업할 때 시간 많이 절약됩니다.

Next.js 15에서 route.js 파일 설정하는 방법

# not-found.js 파일 사용법 - Next.js에서 404 페이지 만들기

안녕하세요! 오늘은 Next.js에서 사용자 정의 404 페이지를 만드는 방법을 소개할게요. `not-found.js` 파일을 사용하면, 특정 라우트(segment)에서 `notFound` 함수가 호출되었을 때 보여질 UI를 쉽게 꾸밀 수 있답니다.

## 기본 개념

- `not-found.js`는 라우트 내에서 `notFound()` 함수가 호출되는 경우, 그에 대한 UI를 렌더링해줍니다.
- 스트리밍 응답(response)인 경우에는 HTTP 상태 코드가 200으로 반환되지만, 스트리밍이 아닌 일반 응답은 404 상태 코드를 반환합니다.
- 즉, 사용자에게 맞춤형 404 페이지를 쉽게 제공하면서 백엔드의 응답 코드는 상황에 맞게 처리해줍니다.

## 예제 코드

아래는 아주 기본적인 `not-found.js` 파일 예제입니다.

```jsx
import Link from 'next/link'
 
export default function NotFound() {
  return (
    <div>
      <h2>Not Found</h2>
      <p>Could not find requested resource</p>
      <Link href="/">Return Home</Link>
    </div>
  )
}
```

- `<h2>` 태그로 큰 제목을, `<p>`로 간단한 안내 문구를 넣었고요.
- `next/link`의 `Link` 컴포넌트를 사용해서 홈으로 돌아갈 수 있는 링크도 만들었어요.

요렇게 하면, 사용자 경험을 높이는 맞춤형 404 페이지를 아주 쉽게 만들 수 있죠!

## 추가 팁!

- `not-found.js`는 라우트 폴더 바로 아래에 위치해야 작동해요. 예: `app/products/not-found.js`
- 더 멋진 UI를 위해 스타일링 라이브러리(Tailwind CSS 등)를 활용해도 좋습니다.
- 404 페이지에서 로그를 남기고 싶다면 컴포넌트 내에서 간단한 클라이언트 또는 서버 사이드 코드 작성도 가능해요.
- Next.js 13 버전 이상의 앱 라우터(App Router) 환경에서만 동작하니 참고하세요!

---

다음에 더 재미있고 유용한 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>

### Props

not-found.js 컴포넌트는 아무런 props도 받지 않습니다.

> 알아두면 좋은 점: 예상되는 notFound() 오류를 잡아내는 것 외에도, 루트에 위치한 app/not-found.js 파일은 여러분 앱 전체에서 처리되지 않는 URL들도 다룹니다. 즉, 사용자가 여러분 앱 내에서 처리하지 않는 URL에 접속할 경우, app/not-found.js 파일에서 내보내는 UI가 보여지게 된다는 뜻이에요.

## 예시

(여기에는 실제 사용 예시나 코드가 들어가면 더 이해하기 좋겠죠? 만약 준비된 예시가 있다면 추가해보세요!) 

---

이 부분을 보면 Next.js 13의 새로운 파일 기반 라우팅에서 404 페이지를 처리하는 방식을 알 수 있어요. 예전에는 별도의 error handling 코드를 많이 짰는데, 이제는 이처럼 not-found.js 파일 하나로 깔끔하게 처리할 수 있습니다. 그리고 루트 디렉토리의 app/not-found.js는 전체 앱에서 처리하지 못하는 URL에 대해서도 자동으로 404 페이지 역할을 하니까, 개발하면서 404 페이지를 따로 신경 쓰지 않아도 된다는 점이 정말 편리해요.

더불어, 만약 특정 경로에서만 커스텀 404 페이지가 필요하다면 하위 폴더에 별도로 not-found.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>

### 데이터 가져오기 (Data Fetching)

기본적으로 `not-found` 컴포넌트는 서버 컴포넌트(Server Component)이에요. 하지만 이 컴포넌트를 `async`로 만들어 데이터를 받아오고 화면에 보여줄 수도 있답니다.

아래 예시를 보면, `headers()`를 통해 요청 헤더에서 도메인 정보를 가져오고, 그 도메인에 맞는 데이터를 비동기로 받아와서 화면에 출력하는 모습이에요.

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

export default async function NotFound() {
  const headersList = await headers()
  const domain = headersList.get('host')
  const data = await getSiteData(domain)
  return (
    <div>
      <h2>Not Found: {data.name}</h2>
      <p>Could not find requested resource</p>
      <p>
        View <Link href="/blog">all posts</Link>
      </p>
    </div>
  )
}
```

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

- `headers()` 함수는 서버에서 실행될 때만 사용할 수 있어요. 클라이언트에서 실행하면 동작하지 않으니 주의하세요.
- 위 예시는 서버 컴포넌트에서 데이터를 가져오는 기본적인 패턴인데, 만약 `usePathname` 같은 클라이언트 훅을 써서 URL 경로에 따라 화면을 다르게 그리고 싶다면, 데이터를 클라이언트에서 가져와야 해요. 그러니까 클라이언트 컴포넌트로 만들어서 `useEffect` 같은 훅을 이용하는 거죠.
- 서버 컴포넌트와 클라이언트 컴포넌트를 혼용할 때는 데이터를 어디서, 어떻게 가져올지 상황에 맞게 설계하는 게 중요합니다.

즉, **비동기 데이터 페칭이 필요하다면 서버 컴포넌트에서 async 함수로 간단하게 처리할 수 있지만, 클라이언트 훅을 사용하고 싶다면 클라이언트 컴포넌트에서 처리하는 걸 기억하세요!**

이해하기 어려운 부분이나 직접 써보고 싶은 팁 있으면 언제든 물어보세요 :)


<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`   | 루트 `app/not-found`가 전역에서 매칭되지 않는 URL들을 처리하도록 변경됨. |
| `v13.0.0`   | `not-found` 기능이 도입됨.                   |

---

여기서 `not-found`는 사용자 경험을 위해 웹사이트에서 404 페이지 같은 '찾을 수 없음' 페이지를 쉽게 구현할 수 있게 도와주는 기능이에요. 특히 `v13.3.0`에서는 앱의 루트 경로에서 전역적으로 매칭되지 않는 URL을 처리하도록 확장돼서, 여러분이 앱 내에서 예상치 못한 경로로 접근할 때도 깔끔하게 안내 페이지를 띄울 수 있답니다.

웹 개발하면서 이런 '404페이지' 처리 중요하죠? 사용자가 잘못된 URL로 들어왔을 때 그냥 에러 메시지 띄우는 것보다 친절한 안내 페이지를 보여주는 게 훨씬 UX 측면에서 좋아요. Next.js 최신 버전들을 사용한다면 이런 기능들을 잘 활용해보세요!

Next.js 15에서 not-found.js로 404 페이지 쉽게 만드는 방법

Next.js 15 page.js로 페이지 구성하는 방법

# loading.js 소개

이번에는 React에서 사용할 수 있는 `loading.js` 파일에 대해 이야기해볼게요. 이 파일은 Suspense를 활용해서 **즉각적인 로딩 상태**를 만들어 주는 역할을 해요.

기본적으로는 서버 컴포넌트(Server Component)로 작동하지만, 필요에 따라 `"use client"` 지시어를 붙여서 클라이언트 컴포넌트(Client Component)로도 쓸 수 있답니다.

---

## 예시 코드

```js
export default function Loading() {
  // 또는 내가 만든 커스텀 로딩 스켈레톤 컴포넌트를 넣어줄 수도 있어요
  return <p>Loading...</p>;
}
```

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

이 파일을 만들어 놓으면 페이지 혹은 컴포넌트가 로딩될 때, 사용자에게 “로딩 중입니다” 같은 상태를 바로 보여줄 수 있어 UX가 훨씬 좋아지죠. Suspense가 컴포넌트를 렌더링하는 동안 이 `Loading` 컴포넌트를 잠시 보여주는 식이에요.

### 꿀팁: 커스텀 로딩 UI 만들기

간단한 텍스트 대신에 애니메이션이 들어간 스켈레톤 UI나 뼈대 화면을 만들어서 넣으면 더 자연스럽고 프로답게 보일 수 있어요. React의 `react-loading-skeleton` 라이브러리를 사용해도 좋고, CSS 애니메이션으로 직접 꾸며줄 수도 있답니다.

---

그럼 다음에는 Suspense랑 함께 이 `loading.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를 설계할 때 React Developer Tools를 이용하면 Suspense 경계(boundary)를 수동으로 토글해보면서 동작을 확인하는 데 큰 도움이 됩니다.

## 버전 히스토리

| 버전       | 변경 사항              |
|------------|-----------------------|
| `v13.0.0`  | `loading` 컴포넌트 도입 | 

추가로, 로딩 UI는 사용자 경험에서 정말 중요한 부분이에요. 너무 짧게 보여주면 깜빡이는 느낌이 들 수 있고, 너무 길면 지루한 느낌을 줄 수 있거든요. 그래서 React Suspense와 함께 사용할 때는 로딩 컴포넌트를 잘 활용해서 자연스러운 화면 전환 효과를 만드는 게 중요해요. React Developer Tools로 직접 토글해보면서 그런 느낌을 체험해 보세요!

Next.js 15 로딩 컴포넌트 만들기 (loading.js)

# mdx-components.js (또는 .tsx) 파일 소개

Next.js에서 `@next/mdx`와 App Router를 함께 사용할 때, `mdx-components.js` (또는 `mdx-components.tsx`) 파일은 꼭 필요한 친구예요. 이 파일이 없으면 MDX를 제대로 쓸 수 없거든요. 게다가 이 파일을 활용하면 MDX 내에서 사용하는 컴포넌트들의 스타일이나 동작을 커스터마이징할 수도 있답니다!

---

## 위치는 어디에?

- 프로젝트 루트 바로 아래에 둬요.  
- 예를 들어, `pages` 또는 `app` 폴더와 같은 레벨에 (또는 `src` 폴더 안에) 두면 좋아요.

---

## 기본적인 작성법

```tsx
import type { MDXComponents } from 'mdx/types'

export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    ...components,
  }
}
```

이 코드는 기본 설정으로 컴포넌트들을 그대로 반환하는 역할을 해요. 여기서 `components`에 우리가 직접 만든 커스텀 컴포넌트들을 덮어씌워서 스타일이나 기능을 내가 원하는 대로 바꿀 수 있죠.

---

## 실제로 커스텀 해보기

예를 들어, MDX 안에서 `<h1>` 태그의 스타일을 바꾸고 싶다면 이렇게 작성할 수 있어요:

```tsx
import type { MDXComponents } from 'mdx/types'

const MyH1 = (props) => <h1 style={{ color: 'tomato', fontSize: '2.5rem' }} {...props} />

export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    h1: MyH1,
    ...components,
  }
}
```

이렇게 하면 MDX 파일 내 `<h1>` 태그가 모두 토마토색 큰 글씨로 바뀌죠.

---

## 참고! 왜 이걸 쓰는 걸까?

MDX 안에는 기본 HTML 태그뿐만 아니라, React 컴포넌트도 자유롭게 넣을 수 있어요. 예를 들어 버튼, 카드, 또는 특별한 레이아웃 컴포넌트 등이죠. 이걸 한 번에 관리하고 싶다면 이 `mdx-components` 파일을 활용해서 확장하거나 수정하는 게 가장 깔끔하답니다.

---

**정리하자면**, `mdx-components.js`(또는 `.tsx`)는 Next.js + MDX 환경에서 커스텀 컴포넌트를 선언하고 스타일을 조절하는 중요한 허브 역할을 하니 꼭 기억하세요! 프로젝트에서 MDX를 쓴다면 이 친구는 필수랍니다 :)

---

필요하면 나중에 커스텀 컴포넌트를 더 만드는 법도 알려드릴게요!


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

## Exports

### useMDXComponents 함수

이 파일은 하나의 함수만 내보내야 해요. 기본 내보내기(default export)로 하거나 `useMDXComponents`라는 이름으로 내보낼 수 있죠.

```js
import type { MDXComponents } from 'mdx/types'

export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    ...components,
  }
}
```

> 여기서 `useMDXComponents` 함수는 MDX 컴포넌트를 커스터마이징할 때 유용해요. 예를 들어, 기본 제공되는 MDX 컴포넌트를 당신만의 스타일이나 새로운 컴포넌트로 대체하고 싶을 때 이 함수를 사용하죠.  
> 그리고 `components` 객체를 받아 그대로 돌려주고 있는데, 필요하면 여기에 새로운 컴포넌트를 추가하거나 기존 컴포넌트를 덮어씌우는 작업도 할 수 있어요.  
>
> 간단한 예를 들어볼게요:  
> js
> export function useMDXComponents(components) {
>   return {
>     h1: (props) => <h1 style={{ color: 'tomato' }} {...props} />,
>     ...components,
>   }
> }
> 
> 이렇게 하면 MDX 내의 모든 `h1` 태그는 토마토색 글씨로 표시되겠죠!   
>  
> MDX로 콘텐츠 작업할 때 아주 많이 쓰이는 패턴입니다.  
> 필요에 따라 잘 커스터마이징해보세요!


<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

### components

MDX 컴포넌트를 정의할 때, export 함수는 단일 파라미터인 `components`를 받습니다. 이 `components`는 `MDXComponents` 타입의 인스턴스인데요.

- **키(key)**는 대체하고자 하는 HTML 태그 이름을 의미합니다.  
- **값(value)**은 해당 HTML 태그 대신 렌더링할 컴포넌트를 지정하는 거죠.

즉, 기본 HTML 요소를 내 마음대로 바꾸고 싶을 때 유용하게 쓸 수 있습니다. 예를 들어, `<h1>` 태그를 나만의 스타일이 입혀진 헤딩 컴포넌트로 교체할 수도 있고, `<a>` 태그를 커스텀 링크 컴포넌트로 바꿔서 새 창 열기 같은 기능을 쉽게 추가할 수도 있답니다.

이걸 활용하면 MDX 문서 내에서 일관된 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>

> 참고할 점: 오버라이드가 없는 다른 컴포넌트들도 모두 전달해주는 것(즉, ...components)을 잊지 마세요.

## 버전 히스토리

| Version     | Changes           |
|-------------|-------------------|
| `v13.1.2`   | MDX 컴포넌트 추가 | 

여기서 MDX 컴포넌트란, Markdown과 React 컴포넌트를 함께 쓸 수 있게 해주는 기능이에요. 프로젝트에서 문서나 블로그 작성할 때 훨씬 유용하게 쓰이니까 꼭 한 번 써보시길 추천합니다!

Next.js 15에서 mdx-components.js로 커스텀 MDX 컴포넌트 만드는 방법

# middleware.js란?

middleware.js(또는 middleware.ts)는 서버에서 요청이 완료되기 전에 중간에 끼어들어 특정 코드를 실행할 수 있도록 도와주는 파일이에요. 즉, 클라이언트가 서버에 요청을 보내면, 해당 요청을 처리하기 전에 이 미들웨어가 먼저 동작하게 되죠.

이걸 쓰면 어떻게 좋냐고요? 예를 들어, 들어오는 요청에 따라 응답을 바꾸거나 리다이렉트 시키거나, 요청이나 응답 헤더를 수정하는 일이 가능해요. 심지어는 바로 응답을 보내버릴 수도 있답니다!

미들웨어는 라우트가 렌더링되기 전에 작동하기 때문에, 인증(auth) 처리, 로깅(logging), 그리고 복잡한 리다이렉트 같은 서버 사이드 로직을 구현할 때 아주 유용하게 쓰여요.

보통 프로젝트 루트에 `middleware.ts` 또는 `middleware.js` 파일을 만들어서 정의합니다. 이 위치는 `app`이나 `pages` 폴더와 같은 수준이거나, `src` 폴더 안일 수도 있어요.

---

### 참고로!

- 미들웨어에서는 **응답을 직접 반환**하면 그 뒤에 라우트 렌더링은 안 되고, 그냥 그 응답이 바로 전송돼요.
- 요청을 **리라이트(rewrite)** 하면 내부 경로 변경이, **리다이렉트(redirect)** 하면 클라이언트에게 다른 주소로 이동하라고 지시하는 의미예요.
- 요청이나 응답 헤더를 자유롭게 조작할 수 있으니, 예를 들어 사용자 에이전트(user-agent)를 검사하거나 쿠키 작업도 가능합니다.

이러면 서버가 좀 더 똑똑해지고, 클라이언트에 맞춤형 응답을 줄 수 있어요!

---

필요하시다면 다음 글에서는 실제 코드 예제와 함께 미들웨어의 구체적인 사용법도 다뤄볼게요~!


<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에서 middleware 작성할 때 기본적으로 export하는 함수는 단 하나여야 한다는 점, 알고 계셨나요? 오늘은 그 부분을 중심으로 간단하게 설명해 보려고 해요.

```js
import { NextResponse, NextRequest } from 'next/server'
 
// 이 함수는 요청을 가로채서 /about 경로 하위에 있는 모든 경로 요청을 /home 으로 리다이렉트 해줘요.
export function middleware(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url))
}
 
export const config = {
  matcher: '/about/:path*',
}
```

위 코드에서 핵심은 `middleware` 함수 하나만 export 하고 있다는 거예요. Next.js는 한 파일에서 여러 미들웨어 함수를 내보내는 것을 지원하지 않아요. 따라서 두 개 이상의 미들웨어가 필요한 경우엔 각각 따로 파일을 만들어야 하죠.

그리고, `config` 객체의 `matcher` 속성은 어떤 경로에 이 미들웨어를 적용할지 정해주는 역할을 해요. 여기서는 `/about/` 경로 이하 모든 경로를 지정했죠. 참고로 `:path*` 부분은 와일드카드 같은 역할을 해서 하위 경로 전체를 포괄할 수 있어요.

### 정리하면

| 항목                 | 설명                                                  |
|--------------------|-----------------------------------------------------|
| 미들웨어 함수          | 꼭 하나만 export 해야 한다                               |
| `matcher` 설정        | 어떤 URL 패턴에 대해 미들웨어를 실행할지 지정               |
| 리다이렉션 처리         | `NextResponse.redirect` 로 요청을 원하는 경로로 보낼 수 있다  |

이런 룰들은 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>

```js
// 기본 export 예제
export default function middleware(request) {
  // 미들웨어 로직 작성
}
```

### config 객체 (선택 사항)

미들웨어 함수와 함께 config 객체를 export할 수도 있어요. 이 객체 안에는 `matcher`가 들어가는데, 이 matcher를 통해 미들웨어가 적용될 경로를 지정할 수 있습니다.

#### matcher

matcher는 미들웨어가 실행될 URL 경로나 패턴을 지정하는 역할을 해요. 예를 들어, 특정 경로나 API 엔드포인트에만 미들웨어가 동작하도록 설정할 수 있죠.

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

위 예시는 `/about`과 `/dashboard`로 시작하는 모든 하위 경로에 미들웨어가 적용된다는 뜻이에요.

참고로, matcher에 지정할 수 있는 패턴은 Next.js의 라우팅 규칙과 비슷해서 익숙하시다면 편하게 쓸 수 있을 거예요.

만약 더 세밀한 조건이 필요하다면, 직접 미들웨어 안에서 request 객체를 검사하는 방법도 있어요. 예를 들어, 쿠키나 헤더에 따라 동작을 조절할 수도 있죠.

미들웨어 설정 시 알아두면 좋은 팁!
- `matcher`를 구체적으로 지정하면 불필요한 미들웨어 실행을 줄여서 퍼포먼스를 개선할 수 있어요.
- 여러 경로를 배열로 전달할 수 있으니 한꺼번에 관리하기 편합니다.
- 잘못된 matcher 패턴은 미들웨어가 의도치 않게 작동하지 않을 수 있으니, 꼭 테스트해보세요!

다음에는 미들웨어 내부에서 실제 request 요청을 다루는 법과 응답 처리 방법에 대해 이야기해볼게요. 그럼 같이 공부해봐요!


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

`matcher` 옵션은 Middleware가 특정 경로에서만 실행되도록 설정할 때 사용해요. 쉽게 말해, 이 옵션을 통해 ‘어떤 경로에 Middleware를 적용할지’를 정할 수 있다는 뜻이죠.

그 방법은 크게 세 가지예요:

- **단일 경로 지정:**  
  그냥 문자열로 경로를 적으면 돼요. 예를 들어, `/about`이면 `/about` 경로에서만 Middleware가 실행됩니다.

- **여러 경로 지정:**  
  배열을 사용해서 여러 경로를 한 번에 지정할 수 있어요.  
  예시) `matcher: ['/about', '/contact']` 이렇게 하면 `/about`과 `/contact` 두 경로 모두 적용됩니다.

- **정규 표현식(Regex) 사용:**  
  더 정교한 경로 필터링이 필요할 땐 정규식도 사용할 수 있어요.  
  예를 들면,  
  js
  matcher: ['/((?!api|_next/static|_next/image|.*\\.png$).*)']
  
  이렇게 하면 `api`, `_next/static`, `_next/image` 폴더나 `.png` 파일 경로는 제외하고 나머지 경로에만 Middleware를 적용해요.  
  정규 표현식의 부정형 전방탐색(negative lookahead)을 활용해 특정 경로나 파일 형식을 꼼꼼히 걸러낼 수 있답니다.

그리고 `matcher` 옵션에는 배열 안에 객체 형식으로 경로를 더 세분화해서 지정할 수도 있는데, 이 객체에는 다음과 같은 키들이 있어요:

| 키 이름      | 설명                                               |
|--------------|----------------------------------------------------|
| `src`        | 적용할 경로를 정의 (문자열 또는 정규식)             |
| `methods`    | 적용할 HTTP 메소드 배열 (예: `['GET', 'POST']`)     |
| `has`        | 요청에 특정 헤더, 쿠키, 쿼리 파라미터가 있는지 조건 지정 |
| `missing`    | 요청에 특정 헤더, 쿠키, 쿼리 파라미터가 없는지 조건 지정 |

이런 식으로 복잡한 조건을 걸 수 있어서, 예를 들어 `POST` 요청이고 특정 쿠키가 있을 때만 Middleware를 적용하는 것도 가능하답니다.

---

### 추가 팁  
Router 미들웨어를 효과적으로 사용하려면, 불필요하게 모든 경로에 Middleware가 실행되지 않도록 `matcher`를 잘 설정하는 게 좋아요. 안 그러면 성능에 영향이 있을 수 있거든요! 또한, Next.js에서 자주 쓰는 `_next/static` 같은 내부 리소스 경로들은 보통 Middleware 대상에서 제외하는 게 일반적이에요.

이 정도만 잘 활용해도 경로별로 딱 맞는 Middleware 적용이 훨씬 수월해질 거예요!


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

요즘 웹 개발할 때, 특정 요청 경로에 맞춰서 로직을 처리하거나 미들웨어를 적용하는 경우가 많죠? 이번에 소개할 내용은 이런 요청 경로 매칭을 세밀하게 조정할 수 있는 설정 방법이에요.

---

### 주요 옵션 설명

| 옵션명     | 설명                                                                                           |
|------------|------------------------------------------------------------------------------------------------|
| source     | 요청 경로를 매칭하는 경로 또는 패턴이에요. 문자열로 직접 지정하거나 복잡한 패턴을 지정할 수 있어요.             |
| regexp     | 정규표현식으로 source를 세밀하게 조절할 수 있어요. 포함하거나 제외할 경로를 더욱 정확하게 조절할 때 쓸 수 있죠. |
| locale     | 불리언 값인데, false로 하면 로케일(언어 설정 등)을 매칭에서 무시해요. 기본값은 true로 다루는 경우가 많습니다.  |
| has        | 요청 헤더, 쿼리 파라미터, 쿠키 등의 특정 요소가 있을 때 조건을 걸고 싶을 때 사용해요.                            |
| missing    | 반대로, 헤더나 쿠키 같은 특정 요소가 없을 때만 동작하도록 조건을 걸고 싶을 때 쓰면 좋아요.                         |

---

### 실제 예제

```js
export const config = {
  matcher: [
    {
      source: '/api/*',
      regexp: '^/api/(.*)',
      locale: false,
      has: [
        { type: 'header', key: 'Authorization', value: 'Bearer Token' },
        { type: 'query', key: 'userId', value: '123' },
      ],
      missing: [{ type: 'cookie', key: 'session', value: 'active' }],
    },
  ],
}
```

- `/api/*` 경로에 대해 매칭합니다.
- `regexp`로 좀 더 정교하게 `/api/` 뒤에 어떤 값이 오든 매칭하도록 했어요.
- 로케일 기반 매칭은 무시(`locale: false`)하고요.
- 요청 헤더에 `Authorization`이 `'Bearer Token'` 이고, 쿼리 파라미터에 `userId=123` 이 있어야 합니다.
- 그리고 `session` 쿠키가 없을 때만 이 설정이 적용되는 거죠.

---

### 참고로!

- `has`와 `missing` 조건은 다중으로 걸 수 있으니, 복합 조건 처리도 편리하게 구성할 수 있습니다.
- `regexp` 쓰면 경로를 한 층 더 정교하게 제어할 수 있어서, 간단한 경로나 특수 문자 포함 경로도 문제없이 처리 가능해요.
- `locale` 설정은 멀티랭귀지 사이트 만들 때 유용하고, 단일 언어 사이트는 보통 false로 두고 쓰기도 합니다.

이렇게 매칭 설정을 잘 사용하면, 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>

Middleware를 정의할 때 기본 내보내기 함수는 하나의 매개변수인 request를 받습니다. 이 request는 NextRequest의 인스턴스로, 들어온 HTTP 요청을 나타내죠.

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

export function middleware(request: NextRequest) {
  // 여기에 Middleware 로직을 작성하세요
}
```

> 알아두면 좋은 점:
NextRequest는 Next.js Middleware에서 들어오는 HTTP 요청을 나타내는 타입이에요. 반면에 NextResponse는 HTTP 응답을 조작하고 돌려보낼 때 사용하는 클래스로 구분되어 있습니다.

## NextResponse

NextResponse는 Middleware 안에서 주로 클라이언트에게 반환할 응답을 조작할 때 사용합니다. 예를 들어, 요청을 리다이렉트하거나 쿠키를 설정하는 등의 작업을 할 수 있죠.

간단한 예시를 보면:

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

export function middleware(request) {
  // 특정 경로로 리다이렉트하기
  if (request.nextUrl.pathname === '/old-path') {
    return NextResponse.redirect(new URL('/new-path', request.url))
  }
  return NextResponse.next()
}
```

이렇게 요청된 경로가 `/old-path`라면 `/new-path`로 리다이렉트 시키고, 그렇지 않으면 다음 미들웨어나 라우터로 요청을 넘기게 됩니다.

또한 NextResponse를 이용해 쿠키를 설정할 수도 있어요. 예를 들어:

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

export function middleware(request) {
  const response = NextResponse.next()
  response.cookies.set('my-cookie', 'my-value', { path: '/', maxAge: 60 * 60 * 24 }) // 1일간 유지되는 쿠키
  return response
}
```

위 예시에서는 응답에 'my-cookie'라는 이름의 쿠키를 추가하는 거죠.

Middleware에서 NextRequest와 NextResponse의 역할을 잘 구분해두면 효과적인 요청 처리 및 응답 제어가 가능하니 꼭 기억해두세요!


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

미들웨어(Middleware)는 NextResponse 객체를 사용할 수 있는데, 이 객체는 Web Response API를 확장한 거예요. NextResponse 객체를 반환하면 쿠키를 직접 조작하거나, 헤더를 설정하고, 리다이렉트를 구현하거나, 경로를 다시 쓸 수 있어서 정말 유용하답니다.

> 참고로 리다이렉트를 구현할 땐 NextResponse.redirect 대신 Response.redirect를 써도 된다는 점! 상황에 맞게 골라 쓰시면 돼요.

## 실행 환경(Runtime)

미들웨어는 Edge 런타임에서만 동작해요. 그래서 Node.js 런타임에서는 사용할 수 없다는 점, 꼭 기억해주세요.

---

### 미들웨어에서 NextResponse를 쓰면 좋은 점

- 쿠키 설정/삭제가 편리해요.
- 헤더를 자유자재로 조작할 수 있어서 보안이나 캐싱 정책 등을 설정할 때 유리하죠.
- 경로 재작성(Rewrite) 기능으로 SEO 최적화나 사용자 맞춤 라우팅이 쉬워져요.

Edge 런타임이라는 건, 쉽게 말해 요청이 사용자와 가까운 서버(Edge)에서 빠르게 처리된다는 뜻인데요. 그래서 미들웨어가 빠른 응답 속도에 도움을 줘서 좋은 사용자 경험을 만들 수 있답니다.

필요할 때 미들웨어와 NextResponse를 적절히 활용해보세요! 개발할 때 꽤 큰 힘이 되어줄 거예요.


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

| 버전       | 변경 사항                                                                                         |
|------------|--------------------------------------------------------------------------------------------------|
| `v13.1.0`  | 고급 미들웨어 플래그(Advanced Middleware flags) 추가                                           |
| `v13.0.0`  | 미들웨어가 요청 헤더, 응답 헤더를 수정할 수 있고, 응답도 직접 보낼 수 있게 개선                  |
| `v12.2.0`  | 미들웨어가 안정화됨. 자세한 업그레이드 가이드는 [여기](https://nextjs.org/docs/messages/middleware-upgrade-guide) 참고 |
| `v12.0.9`  | Edge Runtime에서 절대 URL 강제 적용 ([관련 PR](https://github.com/vercel/next.js/pull/33410))                  |
| `v12.0.0`  | 미들웨어(Beta) 기능 추가                                                                         |

---

*잠깐!*

여기서 말하는 '미들웨어'는 Next.js에서 API 요청과 응답 사이에 원하는 로직을 끼워 넣을 수 있는 기능이에요. 예를 들어 로그인 검증, A/B 테스트, 사용자 맞춤 리디렉션 등을 처리할 때 아주 유용하답니다.

그리고 `v13.0.0`부터는 요청과 응답 헤더를 수정하거나 직접 응답을 보내는 등 훨씬 더 강력한 제어가 가능해져서, 미들웨어를 활용하는 범위가 정말 넓어졌어요.

버전이 올라가면서 미들웨어가 안정화되고 기능도 점점 확장되고 있으니, 현재 개발 중인 프로젝트에 맞춰 적절히 선택해서 쓰시면 좋겠네요!

Posts