모노레포 도입 후기(Feat. Nx)

최근 모노레포라는 개념이 주목받고 있습니다. 모든 코드와 리소스가 하나의 저장소 안에서 관리되는 모노레포 방식은 개발자의 생산성을 높여 준다는 장점을 가지고 있습니다.

 

제가 속해 있던 팀에서도 단순히 새로운 트렌드를 따라가는 것이 아닌, 개발자의 작업 효율과 생산성 향상을 주 목적으로 멀티레포 환경에서 모노레포 환경으로의 전환을 결정하게 되었습니다.

 

이 마이그레이션 과정의 경험과 그 결과에 대한 후기를 작성해 보려고 합니다.

 

 

 

모노레포 도입 배경

 

우선 마이그레이션 전의 상황은 다음과 같았습니다.

 

.
├── AProject
├── BProject
└── CProject

 

• 레포지토리의 형식은 모노레포보다는 모놀리식
  • 한 레포지토리 안에 n개의 프로젝트가 있음
  • 모든 프론트엔드의 코드와 리뷰는 하나의 레포에서 참고할 수 있음
  • 모노레포 툴링 환경(npm workspace, turborepo 등)이 아님
  • 모노레포의 이점(공통 모듈, eslint 환경 설정 등)은 사용하지 못하는 상황

 

 

레포지토리의 형식은 모노레포와 유사한 형식을 띄고 있었으나, 모노레포의 이점을 사용하고 있지 않았으므로 단순 모놀리식이라고 하는 것이 적합합니다. 공통 코드를 공유할 수 없는 구조였기 때문에 사실상 멀티레포에 더 가깝다고 느껴지는 구조였습니다. 

 

모노레포로 가기 전까지는 여러 난관들이 많았습니다. 우선 처음 모노레포의 필요성을 깨달았을 때부터 이야기해 보려고 합니다.

모노레포로 마이그레이션을 하게 된 가장 큰 이유는 프로젝트 간 공통적으로 사용하는 모듈을 관리하는 것에 어려움을 느껴서입니다.

 

 

모노레포의 개념을 알고 있는 사람들이라면 이런 그림을 정말 많이 봤을 것입니다.

이 그림에서는 사용하는 툴, 언어, 라이브러리 등에 초점을 맞추어 설명하고 있지만, 프로젝트 내의 공통 모듈도 같은 경우입니다.

 

예를 들면 리액트의 같은 custom hook을 A 프로젝트, B 프로젝트, C 프로젝트 각각에 작성하여 관리하고 있었기 때문에 하나의 훅을 간단히 한 줄만 리팩토링하거나 컴포넌트의 구조가 조금씩 바뀌는 경우에도 세 파일을 모두 수정해 주어야 했습니다.

 

또한 eslint, prettier 등의 설정을 동일하게 세팅하고 싶을 때도 마찬가지입니다. 하나의 설정을 변경하는 경우 모든 프로젝트에 해당 설정을 적용하고 싶다면 프로젝트의 개수에 대응하는 파일들을 모두 수정해야 합니다. 설정 파일을 하나 변경할 때마다 세 프로젝트의 설정이 언제나 함께 변경되지 않을 때도 있었기 때문에 eslint의 사용하지 않는 규칙 등이 프로젝트마다 각각 달라 코딩 컨벤션이 사소하게 다른 상황이었습니다.

 

겉보기에는 모노레포처럼 보일지 모르는 당시의 환경은 코드 공유 측면에서는 모노레포의 이점을 누릴 수 있었지만(모든 프로젝트의 코드 리뷰를 하나의 레포지토리에서 확인할 수 있다든가) 코드 관리 측면에서는 전혀 아니었습니다. 팀에서는 이러한 번거로움에 불편을 많이 느끼고 있는 상황이었고, 모든 프론트엔드 팀원들과 이야기를 나누어 봤을 때 이 문제를 모노레포 마이그레이션을 통해 해결하는 의견에 모두가 찬성했습니다. 그러나 당시의 팀 상황에서 멀티레포에서 모노레포로 마이그레이션하는 것은 밟아야 할 절차가 매우 많았고, 따라서 가장 비효율적이라고 생각했던 부분을 우선적으로 해결하기 위해 공통적으로 사용할 내부 모듈을 만들어 사용/관리하는 것부터 시작하게 되었습니다.

 

 

팀에서 나눈 단계는 다음과 같습니다.

 

1. 내부 모듈 공통 적용
2. CRA 프로젝트를 Vite로 마이그레이션
3. 모노레포 마이그레이션

 

 

내부 모듈 공통적으로 사용하기

 

여러 프로젝트 간 내부적으로 공통 모듈을 사용하는 방식은 yarn link 를 사용하는 방식을 채택했습니다. (기존 패키지 매니저 yarn 사용)

 

yarn link 는 로컬에서 다른 패키지를 연결하여 사용하는 방법이고, 당시 프로젝트 배포는 CI/CD 환경을 사용하지 않고 aws에 직접 파일을 업로드에 배포하는 환경이었기 때문에 쉽게 적용할 수 있었습니다.

 

 

기존에는 프로젝트마다 hooks 폴더에서 각각 커스텀 훅을 관리하고 있었더라면 공통 모듈 환경 세팅 후에는 Common이라는 프로젝트 내에서 세 프로젝트에서 공통적으로 사용할 수 있는 hooks를 관리하게 되어 같은 기능의 코드가 프로젝트와 버전에 따라 조금씩 달라지는 문제를 해결할 수 있게 되었습니다.

 

# before
.
├── AProject
│    └── hooks
├── BProject
│    └── hooks
└── CProject
    └── hooks

# after
.
├── AProject
├── BProject
├── CProject
└── Common
    └── hooks

 

 

이 스텝에서 react의 hook을 사용하려고 할 때 Uncaught TypeError: Cannot read properties of null (reading 'useState')와 같은 에러가 발생했습니다.

 

이 블로그를 참고하여 공통 모듈을 개발할 경우에는 Common 애플리케이션에서 react를 별도로 설치할 경우에 위 에러처럼 예기치 않은 동작이 발생한다는 것을 파악했습니다. Common에서는 peer dependencies로 react를 선언해 주어야 Common을 사용하는 곳, 예를 들면 AProject의 react 의존성을 Common이 참조하게 되어 의존성 충돌로 발생하는 문제를 해결할 수 있었습니다.

 

 

VITE 마이그레이션

VITE 마이그레이션 배경

모노레포 마이그레이션을 하기 전, CRA → Vite 마이그레이션을 먼저 진행하게 되었습니다.

 

React 공식 문서에서 신규 프로젝트를 생성하는 가이드 부분에 CRA의 안내가 빠진 상태입니다. (참고) 새로운 프로젝트를 시작하려는 경우 Next.js, Remix.js 등 React 기반 메타 프레임워크를 추천합니다. React를 라이브러리로 사용하려는 경우에는 Vite를 번들러로 추천하고 있습니다.

 

외에도 저희 팀에서는 PostCSS 도입을 했으나, CRA는 PostCSS의 커스텀 환경 설정을 지원하지 않기 때문에 eject를 하거나 eject 없이 웹팩 설정을 변경할 수 있는 craco 같은 패키지를 사용해야 합니다. (참고) 프론트엔드 팀 내에서도 이와 관련하여 CRA를 마이그레이션하자는 논의가 이루어지고 있던 상황이었습니다.

 

처음에는 CRA로 생성된 프로젝트를 모노레포로 마이그레이션하려 시도해 보았습니다. 그러나 TypeScript로 작성된 내부 패키지를 컴파일하지 않고도 JavaScript 프로젝트에서 import하여 사용하는 것에 어려움을 겪었습니다. Turborepo의 공식 문서에는 모노레포의 내부 패키지를 TypeScript로, 프로젝트는 JavaScript로 사용할 경우의 솔루션이 나와 있긴 하였으나 Next.js와 Vite를 사용한 경우만 명시되어 있는 상황이었습니다.

 

Nx는 CRA 프로젝트를 Nx Workspace로 마이그레이션하는 방식이 작성되어 있긴 했지만 이는 하나의 애플리케이션을 마이그레이션하는 방법에 대한 문서였고, 멀티레포를 모노레포 형식으로 마이그레이션하는 저희 팀의 상황에는 적합하지 않은 정보였습니다.

 

따라서 장기적으로 보았을 때 Vite의 빌드 성능 개선 등으로 개발 효율성을 얻을 수 있다는 점과 모노레포 마이그레이션이 용이하다는 점을 이유로 모노레포 마이그레이션 타임라인에 CRA 프로젝트를 Vite로 마이그레이션하는 스텝을 추가하게 되었습니다.

 

 

VITE 마이그레이션 중 이슈

프론트엔드 프로젝트는 총 세 개가 있는 상황이었는데, 프로젝트마다 환경이 상이했습니다.

 

• AProject: webpack (CRA eject), JavaScript
• BProject: CRA, craco, TypeScript
• CProject: CRA craco, JavaScript

 

서로 다른 환경을 Vite 마이그레이션 하다 보니 PostCSS 플러그인 설정에서 애를 먹기도 했습니다. AProject는 webpack에서 PostCSS 플러그인을 추가하여 사용하고 있었기 때문에 postcss.config.js로 설정하는 BProject와 달라 스타일이 제대로 표현되지 않는 문제가 있었습니다. 이 문제는 AProject에 postcss.config.js 파일을 추가하여 해결했습니다.

 

프로젝트에서는 glb와 zip 확장자 파일을 사용하는 경우가 있었습니다. 이 파일들을 Vite 빌드에 포함시키려면 추가적인 Vite 플러그인이 필요합니다. 이 부분은 로컬에서 관리하던 glb와 zip 파일들을 AWS S3에 업로드하여 사용했습니다.

 

 

 

VITE 적용 후

동일한 환경에서 비교해 보았을 때 CRA 환경에서는 약 144s 소요되었던 빌드 시간을 Vite 환경에서는 약 24s로, 6배 정도 단축할 수 있었습니다.

 

프로젝트를 실행할 때에도 확실히 체감할 수 있을 만큼 속도가 단축되었는데, CRA 환경에서 길게는 10s 이상 소요되었던 실행 시간이 Vite 환경에서는 약 400ms로 25배 가량 단축되었습니다.

 

코드 변경 후 저장 시에도 CRA는 전체 애플리케이션을 새로고침 하는 데 3~5s 소요되었지만, Vite는 수정된 모듈만 빠르게 로딩하여 반영해 주기 때문에 대부분의 경우 1s 이내에 변경 내용이 반영되어 개발자 경험을 개선할 수 있었습니다.

 

	CRA	VITE
빌드	144s	24s
프로젝트 실행	10s+	400ms
코드 변경 후 새로고침	3~5s	~1s

 

 

 

모노레포 툴 선택

팀 상황은 모노레포를 경험해 본 사람이 없었고, 새로운 프론트엔드 팀원(주로 신입)이 함께할 가능성이 있었습니다. 그렇다면 모노레포를 사용하게 되는 사람은 거의 모노레포를 접하지 않은 사람들일 것입니다. 따라서 저희 팀에서는 yarn workspace 기능을 사용하여 모노레포 환경을 구축하는 것보다 효과적인 모노레포 툴을 도입하여 사용하는 것이 나을 것이라는 판단을 내렸습니다.

 

 

당시 저희 팀에서 리서치한 모노레포 툴은 Lerna, Terborepo, Nx 세 가지가 있었습니다.

 

다른 모노레포 툴과 비교했을 때 Nx는 Nx console이라는 VS Code에서 Nx를 쉽게 사용하기 위한 GUI 툴을 제공합니다. Nx console을 사용했을 때, 새로운 리액트 프로젝트(또는 리액트가 아닌 프로젝트도)를 생성한다거나, 새로운 내부 패키지를 작성한다거나, 모노레포와 병렬적으로 도입을 시도하고 있었던 Storybook이나 cypress를 세팅하는 작업도 손쉽게 할 수 있을 것 같아 보였습니다. 따라서 Nx가 개발자 경험 측면에서 유리할 것이라고 판단했습니다.

 

또한 공식 문서의 다양한 설명과 예제가 존재했고, npm trend로 비교해 보았을 때 다른 툴보다 사용자가 많기 때문에 생태계 측면에서도 유리할 것이라고 생각되어 Nx로 모노레포를 관리하기로 결정했습니다.

 

 

마이그레이션 중 겪은 이슈

기존 레포지토리를 모노레포 형식으로 마이그레이션 하면서 겪었던 이슈들입니다.

 

 

첫 번째로는, 기존 (겉으로 봤을 땐 모노레포 모양을 띄는) 레포지토리에 Nx만 추가하는 형태의 마이그레이션을 할 수 없었다는 문제가 있었습니다.

 

기존 레포지토리는 yarn workspaces이 아닌 yarn link를 사용하여 의존성을 관리하고 있는 형태였기 때문에 모노레포 구조를 띄고 있지는 않았습니다.

 

Nx의 공식 문서를 참고했을 때는 ① npm/yarn/pnpm workspaces에서 마이그레이션하는 방법, ② 모노레포가 아닌 단일 프로젝트에 Nx를 추가하는 방법, ③ 수동 마이그레이션 하는 방법 등이 작성되어 있었습니다. 수동 마이그레이션은 Nx workspace를 새로 생성하고 애플리케이션의 코드나 package.json의 의존성을 수동으로 옮기는 방식이었습니다. 저희 팀에서는 수동 마이그레이션 방식을 사용하기로 했습니다.

 

이 방법으로 마이그레이션을 했을 때, 마이그레이션 전과 후의 차이를 어떻게 조정할지에 대한 고민이 있었습니다. 스타트업에서 서비스 개발은 빠른 속도로 진행되기 때문에 코드 수정은 매일 발생하고, 새로운 레포지토리에서 모노레포 환경을 구축할 것이기 때문에 마이그레이션 이후에 기존 레포지토리에 작성된 코드의 싱크를 어떻게 맞추느냐가 문제였습니다. 따라서 마이그레이션 일정을 따로 협의하게 되었습니다.

 

 

 

두 번째로는, 모노레포 환경을 구축한 새로운 저장소로 코드를 이전할 때 커밋 히스토리까지 옮기는 과정이 필요했습니다.

 

저희 팀에서는 git filter-repo 명령어를 사용하여 커밋 히스토리를 함께 이전했습니다. 외에도 git filter-branch 명령어를 사용할 수 있습니다.

 

 

 

세 번째로는, JavaScript 프로젝트에서 컴파일 하지 않은 TypeScript로 작성된 내부 패키지를 사용하면서 발생한 문제가 있었습니다.

 

yarn add --dev @nx/js

 

Nx에서는 간편하게 @nx/js라는 패키지를 설치함으로서 JavaScript 프로젝트 내에서도 TypeScript로 작성된 모듈을 실행할 수 있었습니다.

 

 

 

네 번째로는, 배포 환경에서 dayjs error가 발생하는 문제가 있었습니다.

 

 

이 문제는 dayjs 공식 문서에 잘 나와 있는데, tsconfig.json 설정과 관련 있었습니다.

tsconfig.json 설정에 따라 import * as dayjs from "dayjs"와 import dayjs from "dayjs" 중 사용 방법이 달라진다고 합니다.

 

 

 

후기

모노레포 환경을 구축하는 것은 프론트엔드 팀의 숙원 사업이었습니다. 동료와 함께 한 달 동안 주에 2회 회사에 남아 늦게까지 원티드에서 주최한 모노레포를 주제로 한 챌린지에도 참여하며 기본 개념을 익히기도 했습니다. 프론트엔드 기술 부채를 해결하기 위해 모인 미팅에서 가장 시급하게 해결하면 좋지만 모노레포를 다뤄 본 경험이 없기 때문에 섣불리 손을 댈 엄두가 나지 않아 저에게는 골칫거리로 여겨지기도 했습니다. 이 글을 빌려 모노레포 마이그레이션 과정을 함께해 준 베일리에게 감사의 말씀을 전합니다. 😆

 

퇴사를 앞두고 마이그레이션을 진행하게 되어 퇴사 D-1까지 마이그레이션을 진행했던 기억이 납니다. 모노레포 같은 경우는 하루 빨리 진행하고 싶은 작업이기도 했고, 늘 어깨에 얹고 있는 짐이라는 생각도 했었어서 거의 마지막 날까지 업무를 수행했지만 굉장히 기뻤고 홀가분한 마음이 들었습니다.

 

Vite 도입 후 production 배포를 위해 Rollup을 사용해야 한다는 점에서 추가적으로 학습해야 하는 부분도 있었습니다. 그러나 이 부분은 완전히 해결하지 못한 채로 퇴사하게 되어 아쉽습니다.

 

마이그레이션을 진행하게 되며 관련 아티클을 굉장히 많이 찾아보았던 기억도 납니다. 화해 팀에서는 2분기동안 모노레포 마이그레이션을 진행했다고 하는데, 초반에는 비효율적인 태스크들의 연속에 지쳐 빨리 도입해 버리고 싶어 했던 생각도 나네요. 진행하고 보니 시간과 노력을 많이 들일 수밖에 없던 작업이었습니다.

 

 

프로젝트를 모노레포 형태로 관리하며 느낀 점들을 정리하면서 글을 마치도록 하겠습니다.

 

• 모노레포 마이그레이션을 통해 가장 비효율적이라고 생각했던 부분, 여러 프로젝트 간 코드를 공유하고 재사용할 수 있도록 하여 개발자들의 생산성을 향상시킬 수 있었습니다.
• 여러 가지 모노레포 툴들을 비교 분석하면서 팀의 요구 사항에 가장 적합한 도구를 선택하고 과거부터 현재까지의 모노레포 동향에 대한 인사이트도 함께 얻을 수 있었습니다.
• 모노레포 프로젝트를 처음 시작했을 때는 미처 생각하지 못했던 부분인 Vite 마이그레이션까지 함께 진행하게 되어 빠르고 간결한 개발 경험까지 얻을 수 있게 되었습니다.

 

 

참고

Lerna is dead — Long Live Lerna

모노레포 적용부터 yarn berry까지

모던 프론트엔드 프로젝트 구성 기법 - 모노레포 개념 편

모던 프론트엔드 프로젝트 구성 기법 - 모노레포 도구 편

번들러 마이그레이션(Webpack to Vite)으로 빌드 속도 높이기

Vite

팀워크 향상을 위한 모노레포(Monorepo) 시스템 구축