[Next.js] next-env.d.ts가 자꾸 바뀌는 문제

pre-commit 테스트를 돌리던 중 생긴 문제...^^;
apps/store/next-env.d.ts 파일이 자동으로 매번 수정되었다.

내가 이 파일을 직접 수정한 적은 없었으나 git에는 변경 사항이 생기고, pre-commit 단계에서 fail했다.

결론부터 말하면 이 문제는 Next.js가 next-env.d.ts를 자동으로 재생성하면서 발생한 이슈였다.

---

next-env.d.ts란?

next-env.d.ts는 Next.js 프로젝트에서 TypeScript 타입 환경을 설정하기 위해 자동으로 관리되는 파일이다.
일반적으로 아래와 같은 내용이 들어 있다.

/// <reference types="next" />
/// <reference types="next/image-types/global" />

// NOTE: This file should not be edited

이 파일은 Next.js가 프로젝트 상태를 보고 자동으로 업데이트하며, 타입 시스템이 깨지는 것을 방지하기 위한 역할임

즉, 프로젝트 설정이 바뀌면 파일 내용이 달라질 수 있다.

---

언제 next-env.d.ts가 다시 생성될까

다음 상황에서 Next.js가 이 파일을 다시 생성한다.

1. next dev
2. next build
3. next lint
4. TypeScript 서버가 프로젝트를 로드할 때
5. Next.js / TypeScript / @types 버전이 변경될 때
6. Router 설정(App Router / Pages Router)이 달라질 때

특히 monorepo 환경에서는 이 현상이 더 자주 나타날 수 있다.

예를 들어 Nx workspace에서 다른 앱의 설정이나 dependency가 바뀌어도
TypeScript 프로젝트 그래프가 다시 계산되면서 파일이 변경되기도 한다.

---

최근 Next.js에서 자주 추가되는 라인

최근 Next.js 버전에서는 아래 라인이 자동으로 추가되는 경우가 많다.

/// <reference types="next/navigation-types/compat/navigation" />

또는 App Router를 사용할 경우

/// <reference types="next/app-types/global" />

내가 파일을 수정하지 않아도 Next.js가 필요하다고 판단하면 강제로 덮어쓰므로 다음과 같은 상황이 발생한다.

git status
modified: apps/store/next-env.d.ts

그리고 pre-commit hook 등에서 테스트가 실패한다.

---

내가 겪은 문제

1. pre-commit 실행
2. nx run store:link 실행
3. Next.js 또는 TypeScript가 프로젝트 상태를 다시 계산
4. next-env.d.ts 자동 수정
5. git 변경사항 발생
6. pre-commit 실패

즉, 테스트가 실패한 것이 아니라 파일이 자동 수정되어서 실패했다.

---

Solutions

Solution 1: next-env.d.ts를 수정하지 않는다

Next.js가 관리하는 파일이므로 직접 수정하지 않는 것이 권장된다.

Solution 2: 한 번 생성된 상태를 커밋한다

git add apps/store/next-env.d.ts
git commit

Next.js가 요구하는 타입 구성이 반영된 상태를 기준으로 커밋하는 것이다.

Solution 3: 팀 환경에서 버전 정렬

이 문제가 발생하는 이유는 다음 중 하나일 수 있다.

• Next.js 버전이 팀원마다 다름
• TypeScript 버전 차이
• @types 패키지 버전 차이
• App Router / Pages Router 혼합 사용

따라서 아래 버전들을 맞춰준다.

• Next.js version
• TypeScript version
• node version
• lockfile 유지 (package-lock.json 또는 pnpm-lock.yaml)

---

monorepo + Nx 환경에서 특히 자주 발생하는 이유

Nx 환경에서는 다음 특징 때문에 더 잘 발생한다.

• 여러 앱이 서로 다른 TypeScript config를 가질 수 있음
• dependency graph가 재계산됨
• 특정 앱에서 Next.js 타입 요구사항이 변경될 수 있음

따라서 어떤 커맨드 실행 시 next-env.d.ts가 수정되는 상황이 생긴다.

---

Summary

next-env.d.ts는 사람이 관리하는 파일이 아니라 Next.js가 관리하는 파일이다.

따라서 아무것도 안 했는데 파일이 바뀌고 CI에서 diff가 발생할 수 있다.

하지만 정상 동작이며 Next.js가 프로젝트 타입 환경을 맞추기 위해 자동으로 업데이트한 것이다.