[💊] 서버 저장소에서 build를 하며 깨닫게 된 yarn.lock 파일의 중요성과 package 버전 동기화 원리

최근 회사의 웹 애플리케이션(Next.js) 정식 릴리즈 배포를 한 후, 저녁에 아래와 같은 버그 이슈 발생을 알게된 후 긴급 대응을 위해 혼자 부랴부랴 저녁 8시부터 새벽 3시까지 고군분투하며 배우고 경험했던 내용을 기록하였다. 🫠

🐞 1. 특정 페이지의 라우팅 시, 무한 로딩 현상 발생

🐞 2. tsx 파일에서 ant design 라이브러리의 특정 UI에 대한 Type Error 발생

📦 지금 회사의 소스코드 배포 방식

내가 지금 다니고 있는 회사에서는 안타깝게도 CI/CD 시스템이 없다. (온프레미스로 운영하는 웹 사이트가 많아서 그럴지도..?)
그말인 즉슨, 프론트와 백엔드 개발자들이 각각 직접 수동으로 서버에 접근하여
git pull -> yarn build -> yarn start 과정을 진행해야 한다는 것이다.
그래서 이직하기 전에 여기서 CI/CD 시스템을 어느정도 구축하고 싶어서 2달 전부터 짬짬이 공부하며 시도 중이지만, bitbucket 버전 관리 솔루션에 대한 CI/CD 설명 정보가 많이 없어서 아직도 고군분투 중이다.
그나마 bitbucket의 Pipelines를 이용하여 push 발생 시, 자동으로 빌드 테스트(CI)를 하는데까지는 성공해서 유용하게 사용하고 있다.

(우리 회사는 Github, Gitlab이 아닌 Bitbucket 저장소를 사용하고 있다.)

🪄 이번 릴리즈 버전 배포를 하면서 업데이트된 사항

사실 이번 배포 때, 생긴 버그 이슈들은 한 개 빼고는 처음 맞이한 것이다. 그래서 최근에 새로운 수정된 내용이 무엇이 있었나 봤더니 아래와 같았다.

• Next.js 프레임워크 버전 업그레이드 (v10.0.7 -> v11.0.0)
• antd UI 라이브러리 버전 업그레이드 (v4.17.0 -> v4.20.0)
• react-i18next locale 라이브러리 버전 업그레이드 (v7.3.0 -> v12.0.0)

🔎 원인 분석

위의 업데이트된 사항을 기반으로 하나하나씩 원인 분석을 하기 시작했다.

1번 이슈 분석

1번 이슈의 원인은 바로 react-i18next 라이브러리 버전을 업그레이드 한 것이다.
기존까지는 react-i18next@v7.3.0 을 사용하였는데, 이번에 최신 버전인 v12.0.0으로 업그레이드 하면서 HOC 방식으로 translation 함수를 page의 props 로 전달해주는 translate() 메서드가 더이상 지원이 되지 않고, withTranslation() 으로 대체해야 한다는 것이다.
그래서, t, tReady 등의 props 가 undefined 로 page props에 return 되면서 이후 렌더링 과정들이 진행되지 않고 계속 로딩 이슈가 발생하였다.

따라서, 단순히 translate() 메서드만 withTranslation() 으로 대체하면 되는 줄 알았으나, 시원하게 실패했다. 그 외 수정해야할 부분이 더 있는 것 같은데 기존에 구성되어 있던 환경 파일 코드들이 너무 복잡하게 되어 있어서 이거는 추후 다음 릴리즈 버전 때, 보완을 해야할 것 같았다.

1번 이슈 해결

그래서, 일단 로컬 저장소에서 translate() 메서드를 제공하는 기존 버전 v7.3.0으로 다운그레이드 하여, 서버에서 pull을 받아 빌드를 진행하여 해결하였다.

2번 이슈 분석

2번 이슈는 이전부터 발생해온 이해가 되지 않았던 이슈였는데, 드디어 원인을 발견했다. (아무래도 경험이 쌓이면서 생기는 감각은 무시 못하나보다)

발생한 antd 'Table' UI Component 의 property Type Error 구문 예시

TypeError: types of property 'labelWrap' are incompatible.
          Type 'string' is not assignable to type...

에러가 발생한 Form 의 labelWrap property 부분

분명 로컬 저장소의 node_modules/antd/lib/form/Form.d.ts 에는 아래와 같이 Form 컴포넌트의 props type에 labelWrap 타입이 명시되어 있었다.

하지만, 서버 저장소에서 node_modules/antd/lib/form/Form.d.ts 파일에는 labelWrap 타입 명시가 되어있지 않았던 것이다. 이전에도 빌드 시, typescript + antd 를 사용한 스크립트 파일에서 이 에러가 종종 발생했었는데 그때마다 임시방편으로 서버 저장소의 .ts 파일에 수동으로 prop 타입을 명시하여 해결해왔었다.

이 이슈의 원인은 바로 로컬 저장소와 서버의 package.json, yarn.lock에 명시되어 있는 antd 라이브러리 패키지 버전은 동일하나 로컬 저장소에서 사용되는 실제 antd 라이브러리 모듈 버전(node_modules/antd/package.json)은 v4.17.0이었지만 서버에서 사용되는 모듈 버전은 < v4.17.0 버전이었 던 것이다.
서버에서 최종 build 시, 로컬 저장소에서 bitbucket 원격 저장소에 push 한 최신 package.json, yarn.lock 파일을 pull 받았지만 이를 기반으로 다시 $yarn install 을 해야 node_modules도 yarn.lock 기준으로 패키지 버전 동기화가 될텐데, 이걸 생략하고 바로 $yarn build && yarn start 를 해버렸으니, 로컬 에서는 발생하지 않았던 type error 가 서버에서는 발생하는 상황이 전혀 이상하지 않은 것이다.

즉 요악하자면, 나는 package.json, yarn.lock 만 최신화 시켰지 실제로 프로젝트 코드에 사용되는 패키지 모듈들이 들어있는 node_modules는 $yarn install 로 동기화를 시키지 않아서 발생한 문제였다.

2번 이슈 해결

따라서, 나는 서버에서 $yarn install && yarn build && pm2 restart {PROCESS_id} && pm2 logs {PROCESS_id} 명령어를 통해 node_modules 를 로컬 저장소와 똑같이 동기화 시켰더니 깔끔하게 이슈가 사라졌다.

마치며

역시나 느끼는거지만 코드는 아무 잘못이 없다.
키보드를 두드린 인간이 잘못이지 🤪