Next.js + TypeScript + App Router 환경에서 tsconfig 타입 꼬임

이번 이슈는 tsconfig.json의 설정으로 인해 Next.js 프로젝트에서 타입 추론이 꼬이면서 발생한 에러에 대한 정리다.

---

✅ 한 줄 요약

tsconfig.json의 "include"에 .next/types를 포함하면, Next.js가 자동 생성한 잘못된 타입 정의까지 타입 검사 대상에 포함되어 에러가 발생한다.

---

1. .next/types에 자동 생성되는 타입

app/ 디렉토리 기반 라우팅을 사용하는 Next.js에서는 내부적으로 props, metadata, routes 등을 분석하여
.next/types/app/XXX/page.ts 같은 타입 파일을 자동 생성한다.

 

예를 들어 다음과 같은 타입이 생성될 수 있다:

// .next/types/app/search/page.ts
export type PageProps = Promise<{
  searchParams: { keyword?: string };
}>

 

즉, props 자체가 Promise로 추론되어 버린다.

 

2. 이 타입 파일이 tsconfig의 "include"에 들어가면?

"include": [
  "next-env.d.ts",
  "**/*.ts",
  "**/*.tsx",
  ".next/types/**/*.ts" // ❌ 이게 문제
]

• TypeScript가 .next/types/... 안의 타입 정의도 실제 타입처럼 강제 적용하게 된다.
• .next/types/app/search/page.ts에서 searchParams가 Promise라고 정의돼 있으면,
• 내가 만든 SearchPage에서 searchParams: { keyword?: string }로 선언해도 타입 오류가 발생한다.

 

3. 더 최악인 경우...

한 번이라도 export default async function SearchPage()처럼 작성했다가 나중에 동기 함수로 바꾸더라도

 

➡️ .next/types는 그 당시 async 버전 기반으로 타입을 생성한 채 그대로 남아 있음
➡️ 타입 캐시를 아무리 삭제해도, tsconfig가 잘못돼 있으면 계속 타입 충돌이 발생함

---

✅ 해결 방법

// tsconfig.json 수정
"include": [
  "next-env.d.ts",
  "**/*.ts",
  "**/*.tsx"
],
"exclude": [
  "node_modules",
  ".next"
]

• .next/types를 타입 검사 대상에서 제외
• 오직 내가 작성한 코드만 타입 검사 대상으로 한정

---

🪓 결론

Next.js는 app/ 기반 라우팅에서 .next/types/ 안에 타입 정의를 자동 생성하는데, 이전 코드의 async 함수나 메타데이터 설정이 남아 있을 경우 잘못된 타입 추론이 유지된다. 이 디렉토리를 tsconfig.json의 "include"에 포함시키면 TypeScript가 이 잘못된 타입까지 적용해서 컴파일 에러가 발생하며, "exclude"에 .next를 명시함으로써 이를 해결할 수 있다.