사내 라이브러리 개발 기록 (feat. monorepo, submodule)

문제 배경

• 코드 컨벤션 상이
  30여 개가 넘는 사내 시스템을 개별 담당자가 관리하며, 상이한 코드 컨벤션으로 유지 보수에 많은 비용이 들어가던 이슈.
• 산재되어 있던 공통 컴포넌트 / 로직
  산재되어 있던 컴포넌트 / 훅 / 유틸리티 함수로 신규 개발 및 운영에 있어 반복적인 공수가 들어가던 이슈
• 패키지 버전 상이
  프로젝트 별 호환되지 않는 패키지 버전을 사용하며 코드 통일성을 해치던 문제.

 

목표

공통 로직(컴포넌트/훅/유틸함수)을 별도의 레포지토리로 분리하고, 독립적으로 빌드가 가능해지게 구성하여 다른 애플리케이션에서도 확장해서 사용할 수 있게 함을 목표로 함.

 

목표 달성을 위하여 다음 방법을 고민했음. (1) 깃 서브 모듈, (2) npm 패키지 개발. 각각의 방법이 저마다의 어려움이 있어 결론적으론 사내시스템 개발에 사용되는 npm 패키지를 개발하기로 정하였음. 

 

 

시도

(1) 깃 서브 모듈 (xx)

별도의 레포지토리를 깃 서브모듈로 불러와 확장해 사용하는 방식에는 다음 문제가 있었음. 

 

1. 어색한 폴더 구조

다음과 같이 하나의 프로젝트 내 여러 개의 node_modules가 위치하는 어색한 폴더 구조가 됨. 다중 node_modules로 실행에는 문제가 없지만 패키지 경로 찾기 오류도 있었음.

📦 부모프로젝트

┣ 📂 node_modules

┣ 📦서브모듈

┃ ┣ 📂 node_modules

 

2. 두통을 일으키는 싱크 맞추기

메인 프로젝트에서는 서브 모듈의 커밋 콘텐츠를 저장하지 않고 commit hash를 저장함. 그래서 서브 모듈에 변경이 있다면, 서브 모듈 변경 사항을 먼저 커밋한 후에 메인 프로젝트에서도 한번 더 커밋을 해야 변경 사항이 반영됨.

서브 모듈의 브랜치는 메인 프로젝트의 브랜치와 별개로 동작하여 메인 프로젝트에 새 브랜치 생성 시 서브모듈 브랜치도 함께 분기해서 사용해야 함. 프로젝트의 수정사항이 생길 때마다 서브모듈 브랜치까지 관리해 주는 것이 꽤나 귀찮은 작업이...

 

(2) npm 패키지 개발 (oo)

버전 관리나 활용도 측면에서 장기적으로 사내시스템 공용 라이브러리 개발이 더 빠른 길이라고 판단함. 그 과정에서 여러 사내 시스템과-디자인 시스템을 분리된 워크 스페이스에서 관리하기 위해 모노레포 도입을 고려했지만... 사실상 ㅠㅠ 

모노레포 아키텍쳐

디자인 시스템 분리를 위해 최종적으로 프로젝트 아키텍처를 위 이미지처럼 바꾸어야 했음. 

비교적 최근에 사내에서 고착된 프레임워크는 asp.net core + react 조합인데, 깃에서는 프론트엔드와 백엔드 코드가 같은 저장소에서 관리되고 있었음.

또한 현재 30여 개가 넘는 사내 시스템은 asp.net core mvc, asp.net wep api, webform 등 일관적이지 않은 아키텍처로 각기 구성된 프로젝트가 많은데, 이 중에 프론트와 백단이 분리되지 않고, 프론트 파일이 서버에서 구성되는 webform 형태의 프로젝트도 많았기에 애초에 디자인 시스템 분리가 어려운 환경이기도 했음. 

기존 아키텍쳐

어떤 프로젝트 관리 방식은 모노레포 아키텍처를 따르고, 어떤 프로젝트는 기존 아키텍처를 유지하는 것, 개발 환경 구조와 깃 저장소 구조가 상이함에서 오는 혼선이 유지보수에 비용을 발생할 수 있겠다는 판단하에 소스 관리 방식은 프로젝트 당 하나의 깃 저장소를 유지하기로! 모노레포 도입은 제외! 사이드 프로젝트 할 때만 사용해 봐야지!

 

 

결론

공통적으로 사용되는 컴포넌트 / 훅 / 유틸함수를 공유할 수 있는 패키지 개발을 목표로 잡음. 현재는 라이브러리 구축 초기 단계로 추가로 생성될 컴포넌트가 매우 많다고 판단하여, 버전 관리에 어려움이 예상되었음. 어느 정도 추가될 컴포넌트가 더는 없겠다는 판단이 이뤄지는 시점에 npm private 패키지 배포 예정! 그전까지 빌드는 다음 방식으로 이뤄짐. 

// 공통모듈: ProjectF
// 대상 프로젝트: ProjectA

"build": "tsc && vite build && rimraf <<ProjectA 의 node_modules 경로>>\\<<공통모듈프로젝트명>> && md <<ProjectA 의 node_modules 경로>>\\<<공통모듈프로젝트명>>\\dist && xcopy /y /s .\\dist <<ProjectA 의 node_modules 경로>>\\<<공통모듈프로젝트명>>\\dist /E && copy <<ProjectF의 package.json 경로>> <<ProjectA 의 node_modules 경로>>\\<<공통모듈프로젝트명>>\\ /Y",

 

또한 스토리북은 UI 전용 라이브러리라서, 훅이나 유틸함수는 별도의 문서화 템플릿 제작 과정이 필요했는데 그 과정에서 상당한 삽질이 있었음. vite lib mode + storybook v8 + typescript  + typedoc를 사용해서 스토리 제작에 최대한 공수가 들지 않게 개발하였고, 그 내용은 다음 포스팅에 이어집니다!