Next.js 빌드 에러가 .next/types에 뜰 때, 원본 라우트 찾는 법

npm run build가 멈췄는데 첫 경로가 app/...이 아니라 .next/types/validator.ts나 .next/types/...로 나오면 생성 파일이 고장 난 것처럼 보인다. 그러나 .next/types는 Next.js가 라우트 정보를 바탕으로 만든 타입 정의가 놓이는 곳이다. 이 파일을 직접 고쳐도 다음 개발 서버나 빌드에서 다시 만들어진다. 지금 필요한 것은 생성 파일을 편집하는 일이 아니라 오류 문구가 검사하던 원본 app 라우트를 찾는 일이다.

Tap to zoom

Next.js의 TypeScript 문서는 next dev, next build, next typegen이 라우트 타입과 next-env.d.ts를 생성한다고 설명한다. Next.js CLI 문서는 next typegen이 전체 빌드 없이 라우트·페이지·레이아웃·Route Handler의 타입 정의를 만들며, 결과를 .next/types에 쓴다고 안내한다. 따라서 .next/types가 오류 위치로 보여도 수정 대상은 생성 파일이 아니다.

next typegen으로 라우트 타입부터 다시 만든다

먼저 현재 라우트 구조로 타입 정의를 다시 만든 뒤 TypeScript 검사를 실행한다. 오래된 .next/types를 직접 편집하거나 오류 줄을 지우지 않는다.

npx next typegen && npx tsc --noEmit

프로젝트의 typecheck 스크립트가 이미 next typegen을 포함한다면 그 명령을 써도 된다.

npm run typecheck

타입 검사만 통과하고 실제 빌드가 실패하는지 확인해야 할 때는 다음 단계에서 빌드를 실행한다.

npm run build

여기서 목표는 생성 파일을 새로 만든 뒤에도 같은 오류가 남는지 확인하는 것이다. 오류가 사라지면 오래된 생성 타입과 현재 라우트가 어긋났던 것이다. 남는다면 오류 문구에서 원본 라우트 단서를 찾는다.

오류 문구에서 원본 라우트 단서를 떼어낸다

타입 에러 전체 문장을 이해하려고 오래 붙잡지 않아도 된다. 처음에는 네 가지만 떼어낸다.

생성 경로: .next/types/...
오류 단서: PageProps / LayoutProps / RouteContext / href
연결된 라우트: app/.../page.tsx 또는 layout.tsx 또는 route.ts
기대한 타입 / 실제 타입:

예를 들어 .next/types/validator.ts가 app/products/[id]/page.tsx의 기본 내보내기나 PageProps를 검사하다 실패했다면, validator.ts를 고치지 않는다. app/products/[id]/page.tsx의 컴포넌트 인자와 params 사용을 확인한다. RouteContext가 보이면 대응하는 route.ts의 handler 시그니처를, href가 보이면 next/link나 router.push에 전달한 경로를 본다.

.next/types/validator.ts
Type 'typeof import("app/products/[id]/page")' does not satisfy ...

이 문장에서 중요한 것은 .next/types/validator.ts 자체가 아니라 import 안의 app/products/[id]/page다. 그 경로가 원본 수정 후보를 알려준다. 정확한 원본 경로가 문구에 없다면 PageProps·LayoutProps·RouteContext 중 어떤 도우미가 실패했는지 보고 같은 종류의 라우트를 찾는다.

PageProps와 href 단서로 app의 원본 파일을 찾는다

.next/types 오류를 원본으로 되돌리는 기준은 오류에 나온 타입 이름이다.

Next.js 문서는 App Router용 PageProps, LayoutProps, RouteContext를 전역 도우미로 생성한다고 설명한다. typed routes를 켠 프로젝트에서는 .next/types의 링크 정의가 잘못된 경로 문자열도 검사한다. 따라서 .next/types를 고치는 대신 오류 단서와 같은 역할을 가진 app 파일을 찾는다.

Tap to zoom

예를 들어 오류가 PageProps와 app/products/[id]/page를 함께 보여주면 수정 범위를 다음처럼 묶는다.

이번 수정 범위:
- app/products/[id]/page.tsx
- 이 페이지의 props 또는 params 선언
- 필요한 경우 이 라우트로 보내는 Link 한 곳

이 범위를 넘어 .next/types/validator.ts, next-env.d.ts, package.json까지 바꾸라는 제안이 나오면 멈춘다. Next.js는 next-env.d.ts도 자동 생성 파일로 설명하며 직접 편집하지 말라고 안내한다.

원본 한 곳만 고친 뒤 생성과 검사를 다시 실행한다

원본 page.tsx, layout.tsx, route.ts 또는 링크 호출부 한 곳만 수정한다. 그다음 생성과 검사를 같은 순서로 반복한다.

npx next typegen && npx tsc --noEmit

오류가 사라지면 원본 라우트와 생성 타입이 다시 맞은 것이다. 같은 .next/types 오류가 남으면 오류가 가리키는 원본 경로와 타입 단서를 다시 확인한다. 새로운 import 오류로 바뀌었다면 Module not found에서 패키지와 파일 경로를 구분하는 순서로 갈라본다.

여기서 ignoreBuildErrors로 먼저 우회하지 않는다. Next.js 공식 문서는 이 옵션을 위험한 설정으로 표시하고, 타입 오류가 있어도 프로덕션 빌드를 만들게 된다고 경고한다. 별도 CI 타입 게이트를 운영하는 팀이 아니라면 원본 오류를 고치는 편이 안전하다.

AI에는 생성 파일이 아니라 원본 후보와 수정 경계를 준다

AI에게 .next/types/validator.ts 전체를 고쳐 달라고 하면 자동 생성 파일을 편집하는 답을 받을 수 있다. 생성 경로는 증거로 주되 수정 대상에서는 제외한다.

Tap to zoom

상황:
Next.js 빌드가 .next/types/validator.ts의 타입 오류로 실패합니다.

오류 단서:
[PageProps / LayoutProps / RouteContext / href와 오류 한 줄]

원본 후보:
[app/.../page.tsx 또는 layout.tsx 또는 route.ts]

요청:
.next/types와 next-env.d.ts는 수정하지 마세요.
원본 후보 한 파일 안에서 타입 불일치 원인 2개만 설명해 주세요.
수정 뒤 확인 명령은 next typegen && tsc --noEmit으로 제시해 주세요.

이 프롬프트의 핵심은 생성 파일은 증거이고 원본 라우트가 수정 대상이라는 경계를 먼저 주는 것이다. AI에게 오류를 네 칸으로 정리하는 형식이 더 필요하면 코드가 안 돌아갈 때 오류를 네 칸으로 나누는 방법을 함께 쓸 수 있다.

마지막으로 아래 다섯 줄을 채운 뒤 저장 여부를 결정한다.

생성 오류 경로:
타입 단서:
원본 app 파일:
다시 실행한 명령:
수정 뒤 결과:

원본 파일을 특정하지 못했거나 생성 파일을 직접 바꿨다면 아직 저장하지 않는다. 원본 한 곳을 고친 뒤 next typegen && tsc --noEmit이 통과하면 다음 빌드로 넘어간다.

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

참고 출처

• Narrowing - TypeScript
• noEmit - TypeScript TSConfig
• TypeScript - Next.js
• next CLI - Next.js