패키지 매니저부터 모노레포까지 (05) - 패키지 매니저 이야기가 왜 monorepo로 이어지는가

monorepo는 유행하는 저장소 구조가 아니라, 패키지와 의존성 경계를 여러 개 다루기 시작했을 때 자연스럽게 등장하는 선택지에 가깝습니다.

들어가며

앞 글에서는 왜 workspace가 필요해지는지를 봤습니다. 패키지가 여러 개가 되면, 설치와 실행과 연결 기준을 하나로 맞추는 일이 중요해진다는 점도 함께 정리했습니다.

그다음에 자연스럽게 따라오는 질문이 있습니다.

여러 패키지를 같은 작업 공간으로 묶는 이야기가, 왜 자꾸 monorepo 이야기로 이어질까요.

이 둘은 자주 같이 언급되지만 완전히 같은 말은 아닙니다. workspace는 패키지 매니저가 여러 패키지를 함께 관리하도록 돕는 기능이고, monorepo는 여러 패키지나 여러 앱을 하나의 저장소 안에서 다루는 방식에 더 가깝습니다. 비슷한 장면에 같이 등장하지만, 바라보는 층위가 다릅니다.

그런데 실제로는 이 둘이 쉽게 연결됩니다. 패키지를 여러 개 운영하고, 그 패키지들이 서로 연결되고, 함께 변경되는 일이 늘어나면 저장소 구조도 그 흐름에 맞게 다시 설계해야 하기 때문입니다.

이 글은 monorepo를 무조건 권하는 글이 아닙니다. 왜 많은 팀이 결국 monorepo를 검토하게 되는지, 그리고 언제는 과하고 언제는 자연스러운 선택인지 기준을 정리하는 데 더 가깝습니다.

monorepo는 무엇을 해결하려는 구조인가

monorepo를 처음 들으면 "코드를 한 저장소에 몰아넣는 방식"처럼 보이기 쉽습니다. 하지만 실제로는 저장 위치보다, 함께 바뀌는 것들을 더 잘 관리하려는 운영 구조라고 이해하는 편이 맞습니다.

예를 들어 이런 상황을 떠올릴 수 있습니다.

• packages/ui의 버튼 컴포넌트를 고치면 apps/web와 apps/admin이 함께 영향을 받습니다
• 공통 타입을 수정하면 여러 앱과 라이브러리에서 동시에 확인해야 합니다
• 빌드 설정, 린트 설정, 테스트 규칙을 여러 저장소에 따로 복사해 두는 일이 번거로워집니다

이때 저장소가 모두 따로 떨어져 있으면 변경이 쉽게 분산됩니다. PR도 여러 개, 버전 맞춤도 여러 번, 공통 설정 동기화도 반복됩니다.

monorepo는 이런 분산 비용을 줄이기 위한 구조입니다. 크게 보면 아래 네 가지를 더 쉽게 만들기 위해 선택됩니다.

여러 패키지의 동시 변경

실제 개발에서는 하나의 변경이 한 패키지에서만 끝나지 않는 경우가 많습니다. 공통 컴포넌트를 바꾸고, 그 컴포넌트를 쓰는 앱도 함께 조정해야 하는 상황이 대표적입니다.

monorepo에서는 이 작업을 한 저장소 안에서 한 흐름으로 처리하기가 더 쉽습니다. 변경 이유와 영향 범위를 한 번에 리뷰하기도 편해집니다.

공통 설정 공유

TypeScript 설정, ESLint 규칙, 빌드 기준, 테스트 스크립트는 여러 패키지에서 비슷하게 반복됩니다. 저장소가 나뉘어 있으면 이 설정이 쉽게 어긋납니다. monorepo는 이런 공통 기준을 한 곳에서 관리하기 좋습니다.

버전과 배포 전략 정리

모든 패키지를 같은 버전으로 묶을지, 각 패키지를 따로 배포할지, 어떤 변경이 어떤 패키지에 영향을 주는지 같은 판단도 한 저장소 안에서 더 일관되게 보기 쉽습니다.

타입과 빌드 경계 확인

패키지가 많아질수록 "어디까지가 공개 API인가", "어느 패키지가 어떤 패키지에 의존하는가", "빌드 순서는 어떻게 되는가"를 계속 확인해야 합니다. monorepo는 이런 경계를 구조적으로 드러내는 데 유리합니다.

즉 monorepo는 코드를 한곳에 몰아넣기 위한 방식이 아니라, 여러 패키지의 연결과 동시 변경을 감당하기 위한 운영 구조에 더 가깝습니다.

왜 패키지 매니저 이해가 먼저 필요한가

여기서 다시 시리즈의 시작점으로 돌아갈 필요가 있습니다. monorepo는 단순히 Git 저장소를 어떻게 나눌지의 문제가 아닙니다. 그보다 먼저, 여러 패키지의 의존성을 어떻게 설치하고 연결하고 해석할지의 문제입니다.

즉 monorepo를 이해하려면 패키지 매니저와 workspace를 먼저 이해해야 합니다.

저장소를 같이 둔다고 자동으로 연결되지는 않습니다

같은 저장소 안에 apps/web와 packages/ui를 넣었다고 해서 곧바로 잘 작동하는 것은 아닙니다. 로컬 패키지를 어떻게 참조할지, 설치는 어디서 할지, 실행은 어떤 단위로 할지 정해야 합니다.

이 지점에서 workspace가 필요해지고, 그 workspace를 어떤 철학으로 다루는지가 다시 npm, Yarn, pnpm의 차이로 이어집니다.

monorepo는 의존성 해석 문제를 더 크게 드러냅니다

패키지가 하나일 때는 잘 안 보이던 문제도, 여러 패키지가 한 저장소에 모이면 훨씬 선명해집니다.

• 유령 의존성이 있는가
• 어떤 패키지가 누구를 직접 의존하는가
• 루트 의존성과 각 workspace 의존성이 어떻게 섞이는가
• 빌드와 테스트가 어떤 순서로 돌아야 하는가

즉 monorepo는 저장소 구조이기 전에, 의존성 경계를 더 정직하게 드러내는 환경이라고도 할 수 있습니다.

그래서 패키지 매니저 이야기를 먼저 이해하고 나면 monorepo도 덜 추상적으로 보입니다. "왜 저장소를 하나로 모으는가"보다 "왜 여러 패키지를 한 흐름으로 관리해야 하는가"가 먼저 보이기 때문입니다.

언제 monorepo가 과하고 언제 필요한가

monorepo가 늘 정답은 아닙니다. 단일 앱 하나를 빠르게 운영하는 단계에서는 오히려 과할 수 있습니다. 저장소를 하나로 묶는 것 자체보다, 그 구조를 운영하는 규칙과 도구를 계속 유지해야 하기 때문입니다.

그래서 저는 monorepo를 "좋은 구조"라기보다 "필요가 생겼을 때 채택하는 구조"로 보는 편이 더 맞다고 생각합니다.

아직 과한 경우

아래와 같은 상황이라면 monorepo가 굳이 필요하지 않을 수 있습니다.

• 배포 단위가 사실상 하나다
• 패키지가 하나이거나 둘뿐인데 함께 바뀌는 일도 거의 없다
• 공통 코드를 패키지로 분리할 만큼 경계가 아직 선명하지 않다
• 저장소를 나눠도 협업 비용이 크지 않다

이때는 단일 저장소 또는 소규모 workspace 정도로도 충분할 수 있습니다.

자연스럽게 필요해지는 경우

반대로 아래 상황이 반복되면 monorepo 검토가 자연스럽습니다.

• 앱과 라이브러리가 자주 함께 바뀐다
• 공통 UI, 공통 타입, 공통 설정을 여러 곳에서 공유한다
• 여러 저장소를 오가며 버전과 변경을 맞추는 일이 잦다
• 한 번의 PR 안에서 여러 패키지의 연결 관계를 함께 확인해야 한다

이쯤 되면 monorepo는 욕심이 아니라 운영 비용을 줄이기 위한 선택이 됩니다.

결국 monorepo를 도입할지의 기준은 유행이 아니라 연결된 변경의 빈도에 더 가깝습니다. 함께 바뀌는 것들이 많다면, 함께 다루는 구조가 자연스럽게 필요해집니다.

시리즈 마무리

이 시리즈는 npm이 무엇인지부터 시작했습니다. 처음에는 단순히 install 명령어를 이해하는 이야기처럼 보일 수 있습니다. 하지만 끝까지 따라오면, 이 주제는 결국 패키지를 어떻게 선언하고, 어떻게 설치하고, 어떻게 여러 개의 경계를 관리할 것인가로 이어집니다.

정리하면 흐름은 이렇습니다.

• npm은 패키지를 다루는 기본 축입니다
• npm 하나로 끝나지 않은 이유는 설치 경험과 구조적 한계가 있었기 때문입니다
• Yarn과 pnpm은 같은 문제를 다른 철학으로 풀었습니다
• 패키지가 여러 개가 되면 workspace가 필요해집니다
• 그리고 그 연결이 많아질수록 monorepo를 검토하게 됩니다

즉 monorepo는 갑자기 등장한 별개의 유행이 아니라, 패키지 매니저와 workspace 이야기를 끝까지 따라갔을 때 만나는 구조적 결론에 더 가깝습니다.

물론 모든 팀이 이 결론에 도달하는 것은 아닙니다. 어떤 팀은 단일 프로젝트로 충분하고, 어떤 팀은 workspace까지만으로도 충분합니다. 하지만 적어도 이제는 monorepo를 "좋아 보이는 유행"이 아니라 "왜 필요해지는지 설명할 수 있는 선택지"로 볼 수 있게 됩니다. 그 점이 중요합니다.

참고

• npm Workspaces: npm이 여러 패키지를 한 루트 패키지 안에서 관리하는 기능을 어떻게 설명하는지 볼 수 있습니다.
• Yarn Workspaces: Yarn이 workspaces와 monorepo를 어떤 맥락으로 다루는지 설명합니다.
• pnpm Workspaces: pnpm이 workspace를 어떤 흐름으로 지원하는지 정리한 문서입니다.
• pnpm: pnpm이 monorepo와 효율을 어떤 강점으로 내세우는지 확인할 수 있습니다.