Next.js 메이저 연속 이관 — 15의 비동기화, 16의 React 19

• 여러 앱이 한 저장소에 있는 프론트엔드 모노레포 (Next 14 → 16, React 18 → 19)

증상

• 신규 앱을 최신 버전으로 시작하려는데 기존 앱을 그대로 둘 수 없음
• 한 앱만 올리면 공유 패키지에서 버전이 충돌

원인

• 모노레포라 런타임이 앱 간에 묶여 있음 — 한 앱의 승격이 곧 전체 승격을 요구
• 메이저 사이에 breaking change가 넓게 깔려 있어 한 번에 올리면 회귀 지점을 특정할 수 없음

조치

Next 15 — Dynamic API 비동기화. 요청에 의존하는 API 6종(cookies · headers · connection · draftMode · searchParams · params)이 동기에서 비동기로 바뀜.

• codemod로 1차 일괄 수정 후 남은 지점만 수동 처리 — 손으로 전수 수정하지 않음
• 클라이언트 컴포넌트에서는 use 훅으로 Promise를 풀어 씀

Next 16 — Turbopack과 React 19.

• Turbopack이 기본 번들러로 승격 — 설정에 블록을 명시해야 경고가 사라짐. 기존 번들러 설정과 공존 가능해 한 번에 갈아엎지 않아도 됨. 다만 기존 번들러 기반 플러그인은 호환성을 개별 확인해야 함
• React 19 승격에서 useRef 타입 처리가 최대 작업량 — 초기값과 null 허용을 명시하지 않으면 타입 에러가 나고, 수정 지점이 앱 규모에 비례해 늘어남
• 서버 전용 패키지 지정 옵션이 experimental에서 최상위로 이동, moduleResolution을 bundler로 변경

공통 이관 방식. 버전별 변경점을 먼저 정리하고 앱에서 실제로 쓰는 API만 추려 대상을 확정. 모노레포 앱을 한 번에 올리지 않고 순차 승격하며 단계마다 동작 확인. 버전이 잠시 어긋나는 구간은 패키지 매니저의 격리 설치로 버팀.

결과

• 14 → 16, React 18 → 19를 서비스 중단 없이 완료
• 빌드 속도 약 55% 단축 (Turbopack 전환)

이 승격이 전제가 된 서버 상태 라이브러리 이관 → TanStack Query v4→v5 이관