Next.js 15에서 params가 Promise로 바뀌면서 생기는 TypeError

[Seon-K]

🐞 문제 상황 (Problem Description)

app/activities/[id]/page.tsx에서 params.id를 사용하려고 했지만 다음과 같이 작성한 코드에서 런타임 오류가 발생했습니다:

export default async function ActivityDetailPage({
  params,
}: {
  params: { id: string };
}) {
  const { id } = params;
}

에러를 해석해보자면, params는 Promise 타입이어야 하는데, { id: string }처럼 일반 객체로 줘서 생긴 오류입니다.

---

💻 환경 정보 (Environment)

• 브라우저: Chrome 138
• 프레임워크: Next.js 15 (App Router), React 19
• 배포 환경: Vercel
• 페이지 경로: app/activities/[id]/page.tsx

---

🔍 발생 원인 분석 (Investigation)

• Next.js 15 공식 문서에 따르면, 레이아웃 및 페이지 컴포넌트에서 params가 Promise 형태로 변경되었습니다.
• 이는 서버 측에서 동적 세그먼트를 비동기적으로 resolve하기 위해 도입된 변경된 사항이라고 합니다.
• 따라서 params를 바로 구조 분해하려 하면 아직 resolve되지 않은 상태이므로 undefined 에러가 발생하게 됩니다.
• 이를 해결하려면 params를 await로 비동기 처리하고, 타입도 Promise<{ id: string }>로 선언해야 합니다.

---

🛠 시도해본 해결 방법 (Attempts)

시도한 방식	결과	설명
{ params }: { params: { id: string } } → const { id } = params	❌ 실패	params가 Promise인 상황에서는 undefined
타입 그대로 유지하고 내부에서 await	⚠️ 불완전	타입은 맞지만 async context 처리 누락
아래처럼 명시적 Promise 처리	✅ 성공	params를 await 처리하여 비동기적으로 접근

---

✅ 최종 해결 방법 (Final Solution)

interface PageParams {
  params: Promise<{ id: string }>;
}

export default async function ActivityDetailPage({ params }: PageParams) {
  const { id } = await params;

  return <div>Activity ID: {id}</div>;
}

---

💡 알게 된 점 (Lessons Learned)

• Next.js 15부터는 params가 Promise로 동작한다.
• 이는 비동기 레이아웃 처리에 맞춰 전역적으로 적용된 변경 사항이므로, layout.tsx, page.tsx 등에서 모두 해당 구조를 고려하면서 params를 가지고 와야 한다.
• 컴포넌트에서 params를 사용할 때 무조건 await 처리해야 하며, 타입도 Promise<{ id: string }> 형태로 지정해줘야 한다.
• 공식 문서에 명시된대로, 기존의 동기 방식 코드는 더 이상 작동하지 않기에 앞으로도 해당 사항을 주의하여 구현해야겠다.

NEXT 공식 문서