그러면 이런 이슈들은 언제 어디서 확인할 수 있지?
Peer Dependency 경고는 보통 패키지 설치 시점에 확인할 수 있다.
예를 들어 pnpm install 등을 실행하면 패키지 매니저가 peer dependency 관련 문제를 알려준다.
WARN Issues with peer dependencies found
packages/next
└─┬ next-intl 3.5.0
└── ✕ unmet peer next@^14.0.0: found 15.0.0이런 peer dependency 이슈는 보통 빌드가 아니라 설치 시점에 먼저 드러난다.
다만 패키지 매니저나 설정에 따라 단순 경고로 끝날 수도 있고, 설치가 실패할 수도 있다.
설치가 되었다고 해서 무조건 안전한 것도 아니다. 빌드는 성공할 수도 있고, 런타임에서 에러가 날 수도 있다.
반대로 Breaking Change 이슈는 빌드 시점 또는 런타임 시점에 발생할 수 있어서 더 위험하다.
예를 들어 아래와 같은 경우가 있다.
| 시점 | 예시 |
|---|---|
| 빌드 시 | 타입이 바뀌어서 TypeScript 컴파일 에러 발생 |
| 빌드 시 | 삭제된 API를 import해서 module not found 에러 발생 |
| 런타임 시 | 함수 동작이 달라져서 화면이 깨지거나 데이터가 이상해짐 |
| 테스트 시 | 기존 테스트 케이스가 실패 |
이런 이슈들은 일부는 빌드 단계에서 바로 잡히지만, 일부는 빌드는 통과하는데 실제 기능 테스트를 해보면 동작이 달라지는 경우도 있다.
그래서 패키지를 업데이트할 때는 단순히 설치와 빌드만 확인하는 것이 아니라, 주요 기능이 실제로 정상 동작하는지도 확인하는 것이 좋다.
패키지 업데이트 시 모든 공식 사이트를 일일이 찾아가서 확인하기에는 부담이 있으므로, 아래와 같은 방식으로 핵심 변경사항을 확인하면 된다.
방법 1. 패키지의 CHANGELOG나 Release Note 확인하기
가장 정석적인 방법은 패키지의 CHANGELOG나 Release Note를 확인하는 것이다.
대부분의 패키지는 GitHub에 릴리즈 노트를 남긴다.
예를 들면 아래와 같다.
https://github.com/vercel/next.js/releases이때 전체 내용을 처음부터 끝까지 다 읽기보다는 BREAKING, Breaking Changes, Migration 같은 섹션을 우선 확인하면 된다.
방법 2. 마이그레이션 가이드 참고하기
메이저 버전 업데이트에서는 보통 공식 마이그레이션 가이드를 제공하는 경우가 많다.
예를 들어 아래와 같은 문서가 있을 수 있다.
Next.js → Upgrading Guide
React → How to Upgradev13 → v14, v14 → v15처럼 메이저 버전을 올리는 경우에는 단순히 패키지만 업데이트하지 말고, 해당 버전의 마이그레이션 가이드를 같이 확인하는 것이 좋다.
방법 3. npm outdated, pnpm outdated로 현황 파악하기
현재 프로젝트의 패키지들이 얼마나 오래되었는지 확인하려면 npm outdated나 pnpm outdated를 사용할 수 있다.
pnpm outdated예를 들어 결과가 아래처럼 나올 수 있다.
Package Current Latest
next 14.1.0 15.2.0
tailwindcss 3.3.2 3.4.1
dayjs 1.11.10 1.11.13이때 버전 차이를 보고 업데이트 위험도를 대략적으로 판단할 수 있다.
next
14.1.0 → 15.2.0
Major 업데이트이므로 breaking change 가능성이 있음
tailwindcss
3.3.2 → 3.4.1
Minor 업데이트이므로 대체로 안전한 편이지만 변경사항 확인 필요
dayjs
1.11.10 → 1.11.13
Patch 업데이트이므로 보통 버그 수정 수준일 가능성이 높음정리하면 아래와 같다.
- Patch (
1.0.0 → 1.0.1): 보통 버그 수정 수준이라 비교적 안전한 편 - Minor (
1.0.0 → 1.1.0): 기능 추가가 포함될 수 있고, 대체로 호환성을 유지하는 편 - Major (
1.0.0 → 2.0.0): breaking change가 있을 수 있으므로 반드시 확인 필요
물론 모든 패키지가 SemVer를 완벽하게 지키는 것은 아니므로 Patch나 Minor라고 해서 무조건 안전하다고 단정하면 안 된다.
다만 일반적으로는 Major 업데이트가 가장 주의가 필요하다.
방법 4. npx npm-check-updates로 한 번에 확인하기
npm-check-updates를 사용하면 업데이트 가능한 패키지 목록을 한눈에 확인할 수 있다.
npx npm-check-updates또는 줄여서 아래처럼 사용할 수도 있다.
npx ncu이 도구는 package.json 기준으로 업데이트 가능한 패키지 버전을 확인할 때 유용하다.
방법 5. Renovate, Dependabot으로 자동화하기
Renovate나 Dependabot을 사용하면 패키지 업데이트가 있을 때 자동으로 PR을 만들어줄 수 있다.
GitHub에 설정해두면 의존성 업데이트가 필요할 때 자동으로 PR이 생성된다.
CI가 설정되어 있다면 해당 PR에서 빌드와 테스트까지 자동으로 실행할 수 있다.
이렇게 해두면 업데이트 후 breaking change가 있는지 어느 정도 빠르게 확인할 수 있다.
정리
결론적으로 패키지 업데이트는 대략 아래와 같은 흐름으로 처리하면 된다.
pnpm outdated로 업데이트 현황을 파악한다.- Patch/Minor 업데이트는 비교적 안전한 편이므로 일괄 업데이트 후 빌드와 테스트를 확인한다.
- Major 업데이트는 해당 패키지의 Migration Guide나 CHANGELOG를 먼저 확인한다.
- 업데이트 후
pnpm install을 실행해서 peer dependency 경고가 있는지 확인한다. - 빌드를 실행해서 타입 에러나 import 에러가 있는지 확인한다.
- 주요 기능을 수동으로 테스트해서 런타임 breaking change가 없는지 확인한다.
모든 패키지의 공식 사이트를 일일이 방문할 필요는 없다.
다만 Major 업데이트인 경우에는 해당 패키지의 Release Notes나 Migration Guide를 확인하는 것이 좋다.