15에서 16으로, 실전 마이그레이션 체크리스트

순서가 중요하다

15에서 16으로 옮길 때 앞의 챕터들에서 다룬 변경을 한꺼번에 손대려고 하면 어디서 뭐가 깨졌는지 구분이 안 됩니다. 아래 순서를 권합니다 — 각 단계가 끝날 때마다 앱을 실제로 띄워서 확인하고 다음으로 넘어가세요.

# 1. 의존성과 codemod부터
npx @next/codemod@canary upgrade latest
npx @next/codemod@canary next-async-request-api .

# 2. 타입 체크로 codemod가 놓친 곳을 찾는다
npx tsc --noEmit

# 3. 이 시점에는 아직 Cache Components를 켜지 않는다
#    (기존 캐시 동작을 유지한 채로 나머지 변경부터 안정화)
npm run build && npm run start

next-async-request-api codemod와 타입 체크만으로도 대부분의 컴파일 에러는 해소됩니다. 여기서 멈추고 스모크 테스트를 한 번 하는 걸 권합니다 — 이 단계까지는 "컴파일되면 대체로 동작한다"는 가정이 유효하지만, 이후 단계(proxy 재설계, 캐시 전환)부터는 컴파일이 성공해도 의미가 달라지는 변경이라 그 가정이 깨집니다.

코드로 잡히지 않는 것들

타입 체크와 빌드가 통과해도 사람이 직접 확인해야 하는 항목이 있습니다.

항목	확인 방법
middleware의 인증 로직이 proxy로 온전히 옮겨졌는가	로그아웃 상태로 보호된 라우트에 직접 접근해본다
Edge 전용 API에 의존하던 코드가 있었는가	proxy.ts에서 Buffer, Node 전용 모듈 사용 여부 검색
원래 캐시되던 고트래픽 페이지가 여전히 캐시되는가	응답 헤더의 캐시 상태, 혹은 백엔드 요청 수 모니터링
webpack 전용 로더/플러그인이 Turbopack에서도 동작하는가	해당 로더가 처리하던 파일을 실제로 임포트하는 화면 확인
클라이언트 컴포넌트에서 params를 여전히 동기로 읽는 곳이 있는가	"use client" 파일에서 params. 직접 접근 검색

이 표는 자동화된 도구가 잡아주지 않는 항목만 모은 겁니다. 표에 없는 나머지(타입 에러, import 경로 등)는 앞 단계의 codemod와 빌드가 이미 걸러줍니다.

Cache Components는 마지막에, 그리고 따로

cacheComponents: true는 다른 변경이 전부 안정된 뒤 별도 배포로 분리하길 권합니다. 이유는 4장에서 다뤘듯 이 플래그 하나가 기존 캐시 동작을 통째로 바꾸기 때문입니다. proxy 마이그레이션 버그와 캐시 전환 버그가 같은 배포에 섞여 있으면 장애가 났을 때 원인을 좁히는 데 시간이 걸립니다. 따로 배포하면 문제가 생겨도 "방금 올린 그 변경"으로 원인이 좁혀집니다.

마지막으로— 이 체크리스트는 이 책에서 다룬 변경 기준입니다. 프로젝트마다 쓰는 서드파티 패키지, 커스텀 서버 설정에 따라 여기 없는 항목이 더 나올 수 있습니다. 릴리스 노트의 "Breaking Changes" 섹션은 업그레이드 당일에 한 번 더 원문으로 훑는 걸 권합니다.