# instrumentation-client.js

instrumentation-client.js|ts 파일은 여러분의 애플리케이션 프런트엔드 코드가 실행되기 전에 모니터링이나 분석 코드를 추가할 수 있게 해줍니다. 이를 통해 성능 추적, 오류 감지 같은 클라이언트 측 관찰성 도구들을 쉽고 빠르게 셋업할 수 있죠.

사용 방법도 아주 간단해요! 파일을 애플리케이션 루트 폴더나 `src` 폴더 안에 넣기만 하면 준비 완료입니다.

## 사용법

(여기서부터 구체적인 사용법을 이어서 작성하면 됩니다.)  

이렇게 미리 모니터링 코드를 두면, 현장에서 발생하는 문제를 더 빨리 발견할 수 있고, 서비스 품질을 높이는데 큰 도움이 되니 꼭 활용해보세요!


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

서버 사이드 계측(instrumentation)과 달리, 클라이언트 쪽에서는 특정 함수를 따로 export할 필요가 없어요. 그냥 원하는 파일 안에 모니터링 코드를 바로 작성해주시면 됩니다.

```js
// 퍼포먼스 모니터링 시작 시점 찍기
performance.mark('app-init')
 
// 애널리틱스 초기화
console.log('Analytics initialized')
 
// 에러 추적 세팅
window.addEventListener('error', (event) => {
  // 에러 추적 서비스로 에러 데이터 전송
  reportError(event.error)
})
```

이렇게 간단히 작성할 수 있죠. 

참고로 `performance.mark()`는 브라우저의 성능 측정 API로, 특정 시점에 표시를 찍어서 나중에 성능 분석 자료로 활용할 수 있어요. 그리고 `window.addEventListener('error', ...)`를 사용하면 페이지 내에서 발생하는 자바스크립트 에러를 잡아내서 별도의 추적 시스템에 전송할 수 있어서 디버깅에 매우 유용합니다.

---

## 버전 히스토리

| Version | Changes                         |
|---------|--------------------------------|
| v15.3   | `instrumentation-client` 도입  |

`instrumentation-client`를 도입하면서 클라이언트 쪽에서도 더 쉽게 모니터링 코드 작성이 가능해졌어요. 이 부분 활용하면 애플리케이션 상태를 실시간으로 추적하거나 성능 병목을 빠르게 찾는 데 큰 도움이 됩니다.

Next.js 15에서 instrumentation-client.js 로 웹사이트 분석 도구 사용하기₩

# instrumentation.js

instrumentation.js|ts 파일은 애플리케이션에 관찰 가능성(Observability) 도구를 통합하는 용도로 사용돼요. 이를 통해 애플리케이션의 성능과 동작을 추적할 수 있고, 실제 서비스 중에 발생하는 문제를 더 효과적으로 디버깅할 수 있답니다.

사용법도 간단해요! 프로젝트 루트 디렉토리에 파일을 두거나, 만약 src 폴더를 사용한다면 그 안에 넣으면 되죠.

## 파일에서 제공하는 주요 기능 (Exports)

(여기에 실제로 어떤 내용이 export 되는지 명시되어야 하는데요, 이어서 있으면 같이 정리해보겠습니다.)

---

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

- 관찰 가능성 도구에는 여러 가지가 있는데, 예를 들어 로그 수집, 메트릭 수집, 트레이싱 등이 있어요. instrumentation.js를 통해 이런 도구들을 한 곳에 모아 효율적으로 관리할 수 있어요.
- 실제 운영 환경에서 문제가 발생했을 때, 미리 설정한 instrumentation 덕분에 원인을 빠르게 파악할 수 있으니 개발, 운영 모두에 큰 도움이 된답니다.
- TypeScript를 사용한다면 .ts 확장자를 사용해 타입 안정성을 더할 수도 있어요.

다음에는 instrumentation.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>

### register (선택 사항)

Next.js 서버가 새로 시작될 때 한 번 호출되는 `register` 함수를 파일에서 export할 수 있어요. 이 함수는 async 함수여도 되고, 주로 초기 설정이나 라이브러리 등록 같은 작업에 사용되죠.

예를 들어, 아래처럼 OpenTelemetry를 연동하는 작업을 할 수 있어요:

```js
import { registerOTel } from '@vercel/otel'
 
export function register() {
  registerOTel('next-app')
}
```

위 코드에서 `registerOTel` 함수는 'next-app'이라는 이름으로 OpenTelemetry를 설정해주는 역할을 해요. 이 부분은 프로젝트에서 필요한 모니터링이나 트레이싱을 할 때 유용하답니다.

### onRequestError (선택 사항)

`onRequestError` 함수도 선택 사항인데요, 이 함수는 HTTP 요청 중 에러가 발생했을 때 실행되도록 만들어져 있어요. 만약 API 라우트나 서버 함수에서 에러 로그를 따로 남기거나 오류를 처리하고 싶을 때 이 함수를 정의해서 사용할 수 있답니다.

---

참고로, `register` 함수 같은 초기화 함수는 앱이 구동될 때 한 번만 실행되기 때문에 무거운 초기 작업이나 설정을 이곳에 모아두면 깔끔하게 관리할 수 있어요. 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>

Next.js에서 onRequestError라는 함수를 선택적으로 내보내서 서버 에러를 커스텀한 관측(Observability) 도구로 추적할 수 있어요.

- 만약 onRequestError 안에서 비동기 작업을 한다면 꼭 `await` 해줘야 해요. 이 함수는 Next.js 서버가 에러를 포착할 때 실행되거든요.
- 여기서 주의할 점! 에러 인스턴스가 실제로 던져진 원본 에러가 아닐 수도 있어요. 특히 Server Components 렌더링 도중 React가 처리한 에러라면 그럴 수 있는데, 이럴 때는 에러 객체의 `digest` 속성을 이용해서 실제 에러 타입을 확인할 수 있답니다.

아래 코드를 보면 실제로 onRequestError에서 에러 정보를 외부 서버로 POST 요청을 보내서 보고하는 간단한 예시를 보여주고 있어요:

```js
import { type Instrumentation } from 'next'
 
export const onRequestError: Instrumentation.onRequestError = async (
  err,
  request,
  context
) => {
  await fetch('https://.../report-error', {
    method: 'POST',
    body: JSON.stringify({
      message: err.message,
      request,
      context,
    }),
    headers: {
      'Content-Type': 'application/json',
    },
  })
}
```

### onRequestError 함수 파라미터

| 파라미터명  | 설명                                                   |
|-------------|--------------------------------------------------------|
| `err`       | 발생한 에러 객체입니다. React가 가공할 수도 있어요.            |
| `request`   | 현재 요청 정보가 담긴 객체입니다.                             |
| `context`   | 요청에 관련된 추가 컨텍스트 정보가 들어있습니다.                   |

이걸 활용하면 서버 에러를 커스텀 로그 서버나 Sentry, Datadog 같은 외부 모니터링 서비스에 손쉽게 연결할 수 있어요. 특히 여러 비동기 작업을 할 때 `await`를 빠뜨리지 않도록 주의해주세요! 안 그러면 에러 추적이 중간에 끊길 수 있거든요.

그리고 `digest` 프로퍼티를 써서 에러 타입을 확인하는 팁! React에서 처리된 에러는 내부적으론 변형될 수 있기 때문에, 원래 에러를 정확히 파악하려면 이걸 참고하면 좋아요.

이 기능을 잘 쓰면 서버 안정성 모니터링에 훨씬 도움 돼서, 문제 발생 시 빠르게 대응 가능하니 꼭 한번 적용해보시길 추천드립니다!


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

이번에는 `onRequestError` 함수에 대해 알아볼게요. 이 함수는 에러가 발생했을 때 호출되며, 세 가지 매개변수를 받아요: `error`, `request`, 그리고 `context`입니다.

```ts
export function onRequestError(
  error: { digest: string } & Error,
  request: {
    path: string; // 리소스 경로, 예: /blog?name=foo
    method: string; // 요청 메서드, 예: GET, POST 등
    headers: { [key: string]: string };
  },
  context: {
    routerKind: 'Pages Router' | 'App Router'; // 사용하는 라우터 종류
    routePath: string; // 라우트 파일 경로, 예: /app/blog/[dynamic]
    routeType: 'render' | 'route' | 'action' | 'middleware'; // 에러 발생 컨텍스트
    renderSource:
      | 'react-server-components'
      | 'react-server-components-payload'
      | 'server-rendering'; // 렌더링 소스
    revalidateReason: 'on-demand' | 'stale' | undefined; // 재검증 사유, undefined 는 일반 요청 의미
    renderType: 'dynamic' | 'dynamic-resume'; // 'dynamic-resume'은 PPR 사용 시
  }
): void | Promise<void>;
```

| 파라미터 | 설명                        |
|----------|-----------------------------|
| `error`  | 발생한 실제 에러, 고유 ID인 `digest` 포함 |
| `request`| 에러와 관련된 요청 정보      |
| `context`| 에러가 발생한 환경 정보를 담고 있음 |

### 파라미터 자세히 살펴보기

- `error`: 항상 Error 타입이며, 여기에 `digest`라는 고유 ID가 있어 에러를 추적하기 좋습니다. 예를 들어, 같은 에러가 여러 번 발생할 경우 이 ID로 쉽게 분류할 수 있죠.
- `request`: 실제 요청 정보입니다. 어떤 경로(`path`)로, 어떤 메서드(`method`)가 쓰였고, 헤더에는 어떤 정보가 담겨있는지 확인할 수 있어요.
- `context`: 어느 라우터에서 발생했는지(`routerKind`), 어떤 라우트 파일에서 발생했는지(`routePath`), 그리고 에러가 일어난 시점(`routeType`)을 알려줍니다. 렌더링 소스(`renderSource`)나 재검증 사유(`revalidateReason`)도 담겨있어, 상황별 대응에 유용해요.

### 추가 팁: 왜 이렇게 복잡한 정보가 필요할까?

에러 핸들링은 단순히 에러 메시지를 로그에 남기는 걸 넘어서, 상황에 맞게 대처하거나 사용자에게 정확한 안내를 해주는 데 중요해요. 예를 들어 `revalidateReason`이 `'stale'`이면 캐시된 데이터를 다시 불러오는 중 문제가 생긴 거고, 이를 활용하면 재시도 로직이나 사용자 안내 메시지를 다르게 할 수 있겠죠.

최근 Next.js 같은 프레임워크가 여러 라우터 시스템과 다양한 렌더링 방식을 지원하면서, 이런 세분화된 정보가 꼭 필요해졌답니다.

---

다음에 이어서 `### Specifying the runtime` 부분도 한 번 살펴볼게요! 혹시 여기까지 궁금한 점 있으면 댓글로 물어봐 주세요 :)


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

instrumentation.js 파일은 Node.js와 Edge 런타임 둘 다에서 동작하는데요, 만약 특정 런타임을 대상으로 하고 싶다면 process.env.NEXT_RUNTIME 값을 활용하면 됩니다.

```js
export function register() {
  if (process.env.NEXT_RUNTIME === 'edge') {
    return require('./register.edge')
  } else {
    return require('./register.node')
  }
}

export function onRequestError() {
  if (process.env.NEXT_RUNTIME === 'edge') {
    return require('./on-request-error.edge')
  } else {
    return require('./on-request-error.node')
  }
}
```

여기서 중요한 점은 process.env.NEXT_RUNTIME이 'edge'인지 아닌지에 따라서 각각 다른 모듈을 require해서 사용하는 방식이에요. 이렇게 하면 동일한 코드베이스에서 런타임 환경에 맞게 동작 방식을 유연하게 바꿀 수 있어서 정말 편리합니다.

---

## 버전 히스토리

| Version   | Changes                                    |
|-----------|--------------------------------------------|
| v15.0.0   | `onRequestError` 추가, `instrumentation` 안정화 |
| v14.0.4   | `instrumentation`에 Turbopack 지원 추가        |
| v13.2.0   | `instrumentation` 실험적 기능으로 처음 소개      |

버전 히스토리를 보면 알 수 있듯, instrumentation 기능이 처음에는 실험적으로 도입됐다가 이후 안정화 되고, Turbopack 같은 최신 툴도 지원이 추가되면서 점점 완성도 있게 발전해온 걸 확인할 수 있어요.

---

개발할 때 runtime 환경 구분이 필요한 경우에는 이렇게 환경변수를 통해 동적으로 모듈을 분기하는 패턴을 자주 쓰게 되는데, Next.js 같은 프레임워크에서 공식적으로 지원하니까 훨씬 편하게 적용할 수 있는 것 같더라고요. 혹시 특정 런타임에서만 동작하는 코드를 작성하려고 하면 참고해보시면 좋을 것 같아요!

instrumentation.js로 웹사이트 성능 측정 도구 만들기

# forbidden.js 파일 설명

Next.js에서 인증 과정 중 forbidden 함수가 호출될 때 표시되는 UI를 커스터마이징할 수 있는 파일이 바로 forbidden.js예요. 이 파일을 통해 사용자가 권한이 없을 때 어떤 화면을 보여줄지 자유롭게 디자인할 수 있답니다. 그리고 중요한 점은, 이 컴포넌트를 렌더링하면 Next.js가 자동으로 HTTP 상태 코드 403(Forbidden)을 반환한다는 거예요.

예를 들어, 기본적인 forbidden.js는 아래처럼 작성할 수 있어요:

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

export default function Forbidden() {
  return (
    <div>
      <h2>Forbidden</h2>
      <p>You are not authorized to access this resource.</p>
      <Link href="/">Return Home</Link>
    </div>
  )
}
```

조금 더 친근하게 메시지를 바꾸거나, 추가적인 안내 문구를 넣어 사용자 경험을 개선할 수도 있겠죠? 예를 들어, 로그인이 필요한 경우라면 로그인 페이지로 바로 가는 버튼을 추가하는 것도 좋은 방법이에요.

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

export default function Forbidden() {
  return (
    <div style={{ textAlign: 'center', margin: '2rem' }}>
      <h2>접근 금지</h2>
      <p>이 페이지에 접근할 권한이 없어요.</p>
      <p>계속하려면 로그인이 필요합니다.</p>
      <Link href="/login">
        <a style={{ color: 'blue', textDecoration: 'underline' }}>로그인 하러 가기</a>
      </Link>
      <br />
      <Link href="/">
        <a style={{ color: 'gray', marginTop: '1rem', display: 'inline-block' }}>홈으로 돌아가기</a>
      </Link>
    </div>
  )
}
```

> 참고로, 이런 방식으로 UI를 커스텀하면 사용자에게 명확한 안내를 제공할 수 있고, 더 나은 사용자 경험(UX)을 만들 수 있다는 점 기억하세요!

## 참고자료
- Next.js 공식 문서: [Error Handling](https://nextjs.org/docs/advanced-features/custom-error-page)
- HTTP 상태 코드 403: [MDN - 403 Forbidden](https://developer.mozilla.org/ko/docs/Web/HTTP/Status/403)


<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

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

## 버전 히스토리

| 버전       | 변경사항                   |
|------------|---------------------------|
| `v15.1.0`  | forbidden.js가 새로 추가됨 |

버전 히스토리를 보면 forbidden.js는 v15.1.0에서 처음 등장했네요. 새로운 컴포넌트를 도입할 때는 이렇게 변경사항을 꼼꼼히 챙겨두면 나중에 관리할 때 정말 도움이 됩니다. 개발하면서 버전 관리는 꼭 습관처럼 하시길 추천드려요!

nextjs 15 접근 금지 페이지 forbidden.js로 쉽게 만드는 방법

# error.js 파일 이해하기: 예기치 않은 에러 처리하기

프로그래밍 하다 보면 갑자기 예상하지 못한 에러가 발생할 때가 있어요. 이럴 때 사용자에게 깔끔한 ‘에러 메시지’를 보여주고, 앱이 갑자기 죽지 않도록 안전하게 처리하는 게 중요하죠. 이번에 소개할 `error.js` 파일은 그런 에러를 잡아내고 사용자에게 알림 UI(화면)를 보여주는 역할을 해요.

---

## 핵심 코드 정리

```js
'use client' // Error boundaries는 Client 측 컴포넌트여야 해요

import { useEffect } from 'react'

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // 에러가 발생하면 콘솔과 같은 에러 리포팅 서비스에 기록하세요
    console.error(error)
  }, [error])

  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => reset()}>
        Try again
      </button>
    </div>
  )
}
```

---

## 주요 포인트

| 항목 | 설명 |
|---|---|
| `'use client'` | 에러 경계(Error Boundary)는 **클라이언트 컴포넌트**여야 한다는 점! 서버 컴포넌트에서는 에러 경계를 사용할 수 없어요. |
| `useEffect` | 에러가 발생하면 로깅(log)하는 부분이에요. 보통 여기에 Sentry, LogRocket 같은 에러 수집 서비스 코드를 넣기도 하죠. |
| `reset` 함수 | 사용자가 “Try again” 버튼을 누르면 이 `reset` 함수가 실행되면서, 문제가 발생한 부분을 다시 렌더링하는 시도를 합니다. |

---

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

- **에러 경계란?**  
  리액트에서는 ‘에러 경계’라는 개념이 있는데, 컴포넌트 트리 어느 한 부분에서 에러가 나더라도, 해당 부분만 격리해서 에러 UI를 보여주고 전체 앱이 멈추지 않도록 도와줍니다.

- **에러 처리할 때 어디에 쓰면 좋을까?**  
  보통 사용자가 조작하는 주요 화면 컴포넌트 주변에 적용하면 좋아요. 예를 들어, 특정 API 호출이 실패하거나, 컴포넌트 내부 상태가 꼬였을 때 앱이 멈추는 걸 방지하죠.

- **추가 아이디어**  
  에러 메시지를 조금 더 사용자 친화적으로 바꾸거나, 에러 상세 내용을 개발자용 로그에만 남기고 사용자는 간단하게 안내하는 것도 좋은 UX 방식입니다.

- **실무 꿀팁!**  
  에러 발생 시 단순히 console.error만 하기보단, 별도의 에러 모니터링 툴(Sentry, Bugsnag 등)과 연동해두면 실시간으로 문제를 감지하고 빠르게 대응할 수 있어서 정말 좋아요.

---

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

error.js는 라우트 세그먼트와 그 안에 중첩된 자식들을 React의 에러 경계(Error Boundary)로 감싸주는 역할을 해요. 만약 이 경계 내에서 에러가 발생하면, 에러 컴포넌트가 대체 UI(fallback UI)로 보여지게 되죠.

![Error Boundary 예시]( /assets/img/2025-04-22-errorjs_1.png )

> 알아두면 좋은 팁!
> React DevTools에서는 에러 경계를 토글해가며 실제 에러 상태를 테스트할 수 있어요.
> 만약 하위 에러 경계에서 발생한 에러가 부모 에러 경계까지 전달되길 원한다면, 에러 컴포넌트 렌더링 시점에 에러를 다시 던지(throw)면 됩니다.

에러 경계(Error Boundary)는 React에서 UI가 예기치 않게 깨지는 상황을 방지하고 사용자에게도 친절한 메시지를 보여줄 수 있는 좋은 방법인데요, React 16 버전부터 도입된 기능이랍니다. 에러 경계 안에서만 렌더링되는 컴포넌트가 문제가 생기면 그 부분만 대체 UI로 교체되고, 전체 앱이 다운되는 걸 막아줘요.

만약 이 기능을 제대로 활용하고싶다면, 한번 직접 React DevTools에서 에러 경계 토글 기능을 사용해 보면서 에러 상태 테스트를 해보는 걸 추천드려요. 실제 서비스에서 에러 상황을 어떻게 커버할지 고민할 때 큰 도움이 될 거예요!

필요하면 이걸로 사용자에게 에러 메시지를 커스텀하거나, 에러 로그를 서버로 보내는 등의 작업도 할 수 있으니 참고하시고요.

## 참고 자료  
- [React 공식 문서 - Error Boundaries](https://reactjs.org/docs/error-boundaries.html)  
- [React DevTools](https://reactjs.org/blog/2019/08/15/new-react-devtools.html)


<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

#### error

`error`는 `error.js` 클라이언트 컴포넌트로 전달되는 Error 객체의 인스턴스입니다.

> 알아두면 좋은 점: 개발 환경에서는 클라이언트로 전달되는 Error 객체가 직렬화되어 원래 에러 메시지를 포함해 디버깅이 더 쉽도록 도와줍니다. 하지만 프로덕션 환경에서는 잠재적으로 민감한 정보가 클라이언트로 유출되는 것을 막기 위해 이 동작이 달라진다는 점 참고하세요.

추가로, 이런 에러 핸들링 방식을 통해 개발할 때에는 에러 메시지를 좀 더 자유롭게 확인할 수 있지만, 실제 운영 환경에서는 안전을 최우선으로 생각하기 때문에 에러 내용이 제한적으로 전달된다는 점 기억해두시면 좋아요. 에러 관련 코드를 작성할 때는 이 점을 고려해 로깅이나 모니터링도 함께 신경 써주세요!


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

#### error.message

- 클라이언트 컴포넌트에서 전달된 에러는 원래의 에러 메시지를 그대로 보여줘요.
- 반면, 서버 컴포넌트에서 온 에러는 예민한 정보를 노출하지 않기 위해 일반적인 메시지와 식별자(identifier)를 보여준답니다.  
  이 식별자, 즉 `errors.digest` 값을 사용하면 서버 로그에서 해당 에러를 쉽게 찾아낼 수 있어요.

#### error.digest

이건 자동으로 생성된 에러 해시 값이에요.  
서버 쪽 로그와 에러를 매칭할 때 아주 유용하죠.  
즉, 사용자에게는 세세한 정보 대신 이 해시값만 보여주고, 개발자는 이 해시값을 통해 문제를 추적할 수 있는 거예요.

---

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

서버 컴포넌트에서 에러 메시지에 상세한 내용을 숨기는 이유는 보안 때문이에요.  
만약 민감한 코드 구조나 데이터가 클라이언트에 노출되면 해커들이 공격에 악용할 수 있거든요.  
그래서 '어떤 문제가 발생했는지'는 알려주되, '어떤 코드에서, 왜'에 관한 자세한 건 서버 쪽에만 기록해서 관리하는 거죠.

이런 구조 덕분에 사용자 경험은 방해받지 않으면서, 개발자는 충분한 디버깅 정보를 확보할 수 있답니다.  

혹시 서버 로그에서 에러를 찾으려면 `error.digest` 값을 복사해서 검색해보세요!  
이게 생각보다 꽤 쏙쏙 잘 맞아 떨어진답니다. 🙂


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

#### 리셋 (reset)

가끔 에러가 일시적인 경우가 있어요. 이런 경우에는 다시 시도하면 문제를 해결할 수 있죠.

에러 컴포넌트에서는 `reset()` 함수를 사용해서 사용자에게 에러에서 복구할 기회를 줄 수 있어요. 이 함수가 호출되면, 에러 경계(error boundary)에 감싸져 있는 컴포넌트를 다시 렌더링하려고 시도합니다. 만약 다시 렌더링에 성공하면 기존의 에러 화면(fallback)이 정상 화면으로 바뀌게 되죠.

사용법은 아주 간단해요. 예를 들어:

```js
'use client' // 에러 경계는 반드시 클라이언트 컴포넌트여야 합니다

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <div>
      <h2>문제가 발생했습니다!</h2>
      <button onClick={() => reset()}>다시 시도하기</button>
    </div>
  )
}
```

위 예제에서 `reset()` 함수가 버튼 클릭 시 호출되고, 이로 인해 오류 상태가 초기화되어 정상 화면을 다시 시도하게 되는 거죠.

---

**추가 팁!**

- `reset()`은 React의 에러 경계 기능과 연동되어 동작하기 때문에, Next.js 13의 `app` 디렉토리 기반에서 클라이언트 컴포넌트로 작성해야 합니다.
- `reset()`을 사용할 땐 오류 발생 시 사용자에게 친절하게 안내하는 UI를 보여주는 게 좋아요. 예를 들어, 에러 내용과 함께 재시도 버튼을 제공하면 사용자 경험이 훨씬 좋아집니다.
- 일시적인 네트워크 문제나 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>

## 예시

### 전역 에러 처리(Global Error)

전역 에러 처리는 조금 덜 흔하지만, 루트 앱 디렉토리에 `global-error.js` 파일을 만들어서 루트 레이아웃(root layout)이나 템플릿(root template)에서 발생하는 에러를 잡을 수 있어요. 특히 다국어 지원(i18n)을 사용할 때도 문제없이 동작합니다. 여기서 중요한 점! 전역 에러 UI는 반드시 `html`과 `body` 태그를 직접 정의해야 해요. 이 파일이 활성화되면 해당 루트 레이아웃이나 템플릿을 대체하게 된답니다.

```jsx
'use client' // 에러 바운더리는 클라이언트 컴포넌트여야 해요

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <html>
      <body>
        <h2>문제가 발생했어요!</h2>
        <button onClick={() => reset()}>다시 시도하기</button>
      </body>
    </html>
  )
}
```

### 추가 팁!

- `reset` 함수는 에러 상태를 초기화해서 컴포넌트를 리프레시하는 역할을 해요. 사용자 경험을 위해 꼭 넣어주세요.
- 전역 에러 컴포넌트가 활성화되면 기존의 레이아웃이나 템플릿이 완전히 대체되니, 디자인 요소나 공통 레이아웃을 포함시키고 싶으면 직접 만들어야 한다는 점 기억하세요.
- **에러 경계(Error Boundaries)**는 클라이언트에서만 동작하기 때문에 꼭 `'use client'`를 선언해야 하는 점도 꼭 체크!  

이렇게 전역에서 에러를 처리하면 예상치 못한 문제가 발생해도 깔끔하게 사용자에게 안내할 수 있어서 앱 안정성에 큰 도움이 됩니다.


<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.2.0`    | 개발 환경에서 `global-error`도 표시되도록 변경됨. |
| `v13.1.0`    | `global-error` 기능 추가됨.             |
| `v13.0.0`    | `error` 기능 추가됨.                    |

---

여기서 잠깐!  

- `global-error`는 전역적으로 발생하는 에러를 한눈에 확인할 수 있게 해주는 기능이에요. 특히 개발할 때 어디서 문제가 생겼는지 빠르게 파악할 수 있어서 무척 유용하죠.
- 버전 히스토리를 잘 확인해두면 새로 추가된 기능이나 변경된 점을 놓치지 않을 수 있으니 개발하면서 꼭 참고하시길 추천해요!

Next.js 15에서 error.js 파일로 에러 처리하는 방법 정리

# default.js 파일에 대해 알아보자

안녕하세요! 오늘은 Next.js에서 Parallel Routes를 사용할 때 나오는 `default.js` 파일에 대해 이야기해볼게요. Next.js를 쓰다 보면 우리가 원하는 화면(서브페이지)을 보여주다가도, 가끔 새로고침(하드 네비게이션)을 하면 그 상태를 잃어버리고 다시 렌더링해야 할 때가 있잖아요? 이 문제를 해결해주는 게 바로 `default.js` 파일이에요.

---

## default.js 파일, 왜 필요할까?

Next.js는 **소프트 네비게이션**(페이지를 새로고침하지 않고 이동할 때)에서는 각 슬롯(slot)의 액티브 상태를 잘 기억하고 있답니다. 그래서 사용자가 어디에 있었는지 그대로 보여줄 수 있죠.

그런데, 만약 **하드 네비게이션**(진짜 페이지를 새로 고침하거나 처음 방문하는 경우)이 발생하면 액티브 상태를 기억하지 못해요. 그래서 이때, 현재 URL과 맞지 않는 서브페이지가 있을 때 렌더링할 기본 화면을 제공해주기 위해 `default.js`가 필요하답니다.

---

## 예시 폴더 구조 살펴보기

아래처럼 폴더 구조를 보면, `@team` 슬롯에는 `settings` 페이지가 있는 반면, `@analytics`는 없어요.

app
├── layout.js
├── page.js
├── @team
│ ├── page.js
│ └── settings
│ └── page.js
└── @analytics
└── page.js

위처럼 되어있다면, `@analytics` 슬롯에 `settings` 페이지 같은 게 없어 하드 네비게이션 시 상태 복구가 힘들기 때문에, 이때 `default.js`가 빈 슬롯 내용이나 기본 안내 메시지를 보여주는 역할을 하게 되는 거죠.

---

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

- `default.js`는 슬롯 내부의 서브페이지가 현재 URL과 맞지 않을 때 보여주는 **fallback UI**입니다.
- 이를 활용하면 페이지가 완전히 새로고침되어도, 깨지지 않고 친절한 기본 메시지를 띄울 수 있죠.
- 이 기능을 통해 탭이나 메뉴처럼 여러 슬롯을 가진 복잡한 UI를 만들 때 유저 경험이 훨씬 좋아져요.

---

궁금한 점 있으면 댓글로 남겨주세요! 다음에도 재미있고 유용한 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>

위 내용을 쉽게 풀어서 설명해드릴게요.

---

Next.js에서 /settings 경로로 이동하면, `@team` 슬롯에는 설정 페이지가 보여지고, `@analytics` 슬롯은 현재 활성화된 페이지를 계속 유지해요.

**여기서 슬롯(@team, @analytics)이란?**  
페이지를 여러 영역으로 나누고, 각 영역에 다른 컴포넌트를 꽂아 넣을 수 있는 공간 같은 개념이에요. 그래서 한 페이지 안에서도 독립적으로 여러 컴포넌트가 관리됩니다.

---

그런데, 새로고침을 하게 되면 Next.js는 `@analytics` 슬롯에 대해 `default.js` 파일을 찾으려고 해요. 만약 `default.js`가 없다면 404 (페이지 없음) 오류를 띄웁니다.

또 하나 중요한 점!  
`children` 슬롯은 암묵적으로 존재하는 기본 슬롯인데요, 이 `children` 슬롯도 `default.js` 파일을 만들어 줘야 해요. 그래야 Next.js가 부모 페이지의 활성 상태를 복구하지 못할 때 대체할 컴포넌트를 보여줄 수 있어요.

---

### 요약하자면

| 상황                        | 해야할 일                           | 이유                                                              |
| --------------------------- | ----------------------------------- | ----------------------------------------------------------------- |
| /settings 접근 시           | @team 슬롯에 설정 페이지 렌더링     | 해당 슬롯에 지정한 컴포넌트만 바꾸고 다른 슬롯은 유지하기 위해    |
| 새로고침할 때               | `@analytics/default.js` 만들어 두기 | 새로고침 시 기본으로 보여줄 컴포넌트가 필요, 없으면 404 오류 발생 |
| 암묵적 기본 슬롯 `children` | `children/default.js`도 만들어 주기 | 부모 페이지 상태 복구 실패 시 대체 컴포넌트를 보여주기 위해       |

---

### 추가 팁!

- 이렇게 슬롯별로 `default.js`를 준비해두면 사용자 경험이 한층 좋아져요. 새로고침 후에도 오류 대신 기본 페이지가 적절히 렌더링 되거든요.
- 만약 `default.js`가 없으면, 사용자가 새로고침할 때 꽤 당황스러운 404를 보게 되니 꼭 챙겨주세요!

---

이 정도만 알고 있어도 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>

## 참고 자료

### params (선택 사항)

`params`는 루트 경로부터 슬롯 내부의 하위 페이지까지의 동적 라우트 매개변수를 담고 있는 객체를 반환하는 **Promise**입니다. 쉽게 말해, 서버나 페이지가 렌더링될 때 URL 경로에서 변하는 부분들을 비동기적으로 받아오는데 사용돼요.

예를 들어 아래 코드를 보면:

```js
export default async function Default({ params }: { params: Promise<{ artist: string }> }) {
  const { artist } = await params;
}
```

`params`는 `{ artist: string }` 타입을 가진 Promise를 받는데, 여기서 `artist`는 URL 경로의 동적 부분입니다 (`/artist/:artist` 같은 라우트).

---

### 좀 더 쉽게 풀어볼까요?

- 동적 라우팅(dynamic routing)은 URL 경로가 고정된 게 아니라, 변수처럼 변하는 부분을 말해요. 예를 들면, 프로필 페이지 URL이 `/profile/john`과 `/profile/jane`처럼 각각 다를 때, `john`이나 `jane`이 동적 매개변수가 되는 거죠.
- Next.js 13의 App 디렉토리에서는 이런 동적 매개변수를 `params` Promise로 받아 사용할 수 있게 해줍니다.
- 그리고 `params`는 Promise 타입이기 때문에, async/await을 써서 값을 받아와야 하는 점 꼭 기억하세요!

---

### 팁

- 서버 컴포넌트는 기본적으로 async 함수로 만들 수 있으니, 동적으로 데이터를 불러와야 할 때는 이 `params`를 활용하면 아주 편리해요.
- 만약 여러 개의 동적 파라미터가 있다면, `params` 객체에 여러 키가 포함돼서 옵니다. 예를 들어, `/artist/:artist/album/:albumId` 라우트의 경우 `{ artist: string; albumId: string }` 형태로 받겠죠.
- 이 `params`를 잘 활용하면 클라이언트에서 URL을 참고해 요청을 전달하거나 데이터를 동적으로 렌더링하기 훨씬 수월해집니다.

이렇게 `params` Promise를 통해 쉽고 똑똑하게 동적 라우팅 데이터를 다룰 수 있다는 점 기억해두세요!



<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`가 어떻게 전달되는지 예제를 통해 정리한 내용이에요.

| Example                                    | URL          | `params`                                     |
| ------------------------------------------ | ------------ | -------------------------------------------- |
| `app/[artist]/@sidebar/default.js`         | `/zack`      | `Promise<{ artist: 'zack' }>`                |
| `app/[artist]/[album]/@sidebar/default.js` | `/zack/next` | `Promise<{ artist: 'zack', album: 'next' }>` |

여기서 중요한 점은, `params`가 Promise 형태라는 거죠. 그래서 `params` 값을 실제로 사용하기 위해서는 `async/await` 또는 React의 `use` 함수를 써야 해요. 예를 들어, 이렇게 쓸 수 있죠:

```jsx
const params = await props.params; // 또는 React 18의 use 함수 사용
```

버전 14 이하에서는 `params`가 동기적으로 바로 사용 가능했는데, Next.js 15부터는 비동기로 변경되면서 사용법도 달라졌답니다. 다만, 지금 당장은 이전 방식도 호환을 위해 지원하긴 하지만 곧 deprecated될 예정이에요. 그러니까 코드를 새로 쓸 때는 이 부분 꼭 염두에 두는 게 좋아요.

추가로, `params`가 Promise라는 점은 뭔가 데이터가 비동기적으로 준비된다는 걸 의미하기도 해요. 따라서 페이지의 서버사이드 렌더링이나 데이터 페칭 로직과 잘 맞물려서 설계해야 부드러운 UX를 만들 수 있습니다.

이 부분 혼동되기 쉬운데, 꼼꼼히 체크해서 다음 프로젝트에 제대로 적용해보세요!

Posts