Next.js params Promise 오류, Server와 Client를 가른 뒤 고치는 법

AI가 만든 app/posts/[slug]/page.tsx를 열었더니 개발 화면은 그럴듯한데 npm run build에서 params가 Promise라는 타입 오류가 날 수 있습니다. 이때 페이지를 다시 만들거나 Next.js 버전을 내릴 필요부터는 없습니다. 파일 맨 위의 'use client' 유무를 보고 두 경로 중 하나만 고치면 됩니다.

Server Component라면 params: Promise<{ slug: string }>로 타입을 잡고 await params로 풉니다. Client Component라면 async 컴포넌트로 바꾸지 말고 React의 use(params)를 사용합니다. 두 방식을 한 파일에 섞지 않는 것이 이번 점검의 핵심입니다.

Tap to zoom

오류가 난 파일에서 'use client'부터 확인합니다

Next.js 공식 오류 문서는 params와 searchParams가 Next.js 15에서 비동기 API로 바뀌었다고 설명합니다. 예전 예제처럼 params.slug를 바로 읽으면 경고나 빌드 오류를 만날 수 있습니다. 먼저 오류가 난 파일의 첫 줄을 봅니다.

'use client'

이 줄이 없다면 App Router의 page와 layout은 기본적으로 Server Component입니다. 이 줄이 있다면 Client Component 경로로 갑니다. 오류 문구만 AI에게 던지는 대신 파일 경로, 첫 줄, 현재 params 타입을 함께 주면 수정 범위가 줄어듭니다.

app/posts/[slug]/page.tsx 빌드 오류를 고쳐 주세요.
이 파일에는 'use client'가 없습니다.
params 타입과 값을 읽는 부분만 현재 Next.js 공식 방식으로 수정하고,
다른 데이터 요청이나 UI 코드는 바꾸지 마세요.

Server Component는 Promise 타입과 await를 한 쌍으로 고칩니다

Server Component에서 흔히 남는 예전 형태는 다음과 같습니다.

export default function Page({
  params,
}: {
  params: { slug: string }
}) {
  return <h1>{params.slug}</h1>
}

현재 page API 문서의 형태에 맞추면 컴포넌트를 async로 만들고, 타입을 Promise로 바꾼 뒤 값을 꺼내는 시점에 await합니다.

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  return <h1>{slug}</h1>
}

세 군데가 함께 바뀌었는지 봅니다. 함수의 async, params의 Promise 타입, await params가 한 묶음입니다. 타입만 Promise로 바꾸고 params.slug를 그대로 두면 다음 오류가 남습니다.

Next.js가 생성한 라우트 타입을 활용하고 싶다면 PageProps helper도 선택할 수 있습니다.

export default async function Page(props: PageProps<'/posts/[slug]'>) {
  const { slug } = await props.params
  return <h1>{slug}</h1>
}

이 helper의 타입은 next dev, next build, next typegen 과정에서 생성됩니다. 처음 오류를 좁히는 중이라면 명시적 Promise 타입으로 원리를 확인한 뒤 helper로 정리해도 됩니다.

Client Component는 async 대신 React의 use를 씁니다

클릭 상태나 브라우저 API 때문에 파일에 'use client'가 있다면 같은 수정법을 쓰지 않습니다. Client Component 자체를 async 함수로 만드는 대신 React의 use로 Promise를 풉니다.

'use client'

import { use } from 'react'

export default function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = use(params)
  return <h1>{slug}</h1>
}

여기서 판단 기준은 간단합니다. 브라우저 상호작용이 꼭 필요한 page라면 use(params)를 적용합니다. 상호작용 부분만 작은 하위 Client Component로 내릴 수 있다면 page는 Server Component로 유지하고 await params를 쓰는 구조도 검토할 수 있습니다. 오류 하나를 고치려고 파일 전체의 렌더링 경계를 바꾸지는 마세요.

page만 고쳤는데 빌드가 멈추면 같은 패턴을 더 찾습니다

공식 문서상 이 변화는 page 하나에만 적용되지 않습니다. 동적 route의 layout, generateMetadata, Route Handler context에서도 params를 Promise로 받습니다. 첫 파일을 고친 뒤 같은 직접 접근이 남았는지 검색합니다.

rg "params\." app

rg가 없다면 편집기의 전체 검색에서 params.를 찾습니다. 각 결과를 무조건 바꾸지 말고 다음 세 가지를 확인합니다.

1. Next.js가 page, layout, metadata, route handler에 넘긴 params인가?
2. 해당 파일은 Server인가 Client인가?
3. 이미 상위 코드에서 Promise를 풀어 일반 객체로 넘긴 값은 아닌가?

Route Handler도 같은 원리로 context의 Promise를 기다립니다.

export async function GET(
  _request: Request,
  { params }: { params: Promise<{ slug: string }> }
) {
  const { slug } = await params
  return Response.json({ slug })
}

검색 결과를 일괄 치환하지 말고 파일 역할별로 확인해야 이미 일반 객체가 된 값까지 망가뜨리지 않습니다.

수정의 끝은 저장이 아니라 프로덕션 빌드 성공입니다

Tap to zoom

파일을 저장한 뒤 개발 화면만 새로고침하고 끝내지 않습니다. 이번 문제는 타입 생성과 프로덕션 빌드에서 드러나기 쉬우므로 다음 명령으로 확인합니다.

npm run build

빌드가 통과하면 동적 페이지 URL도 하나 직접 엽니다. 예를 들어 폴더가 app/posts/[slug]라면 실제 존재하는 slug로 /posts/hello를 확인합니다. 성공 기준은 빌드 종료 코드 0과 동적 값이 화면에 표시되는 상태입니다.

다른 파일에서 같은 오류가 나오면 첫 수정이 실패한 것이 아닙니다. 빌드가 다음 미해결 위치를 알려 준 것입니다. 파일 하나씩 Server/Client를 가르고 같은 점검을 반복합니다. 공식 codemod인 next-async-request-api도 있지만, AI가 만든 프로젝트에서는 실행 전 커밋이나 별도 브랜치를 남기고 변경 diff를 확인하는 편이 안전합니다. AI 코드 저장 전 바뀐 파일을 보는 기준과 별도 worktree에서 실험하는 순서를 함께 쓰면 되돌리기 쉽습니다.

공식 확인 링크와 오늘의 다음 행동

• Next.js Docs: Dynamic APIs are Asynchronous: 비동기 API 변경과 Server/Client 수정 예제
• Next.js Docs: page.js: page의 Promise 타입과 PageProps helper
• Next.js Docs: layout.js: layout의 params 규칙
• Next.js Docs: route.js: Route Handler context의 params 규칙

오늘은 오류가 난 파일 하나를 열고 'use client' 유무를 표시한 뒤, 맞는 예제 하나만 적용하세요. 그 다음 npm run build를 실행해 다음 오류 위치 또는 성공 상태를 기록하면 됩니다.

이 글은 AI 코딩과 개발 학습의 일반 정보 제공 목적입니다. 도구, 모델, 커리큘럼, 요금은 버전과 시점에 따라 달라질 수 있으므로 실습이나 도입 전 공식 문서와 최신 릴리스 노트를 확인하세요.