2nd/10_Wiki/Topics/Frontend_Mastery/대규모 확장성과 유지보수성이 요구되는 프런트엔드 모노레포 프로젝트.md

대규모 확장성과 유지보수성이 요구되는 프런트엔드 모노레포 프로젝트

📌 Brief Summary

현대적인 프런트엔드 모노레포는 웹 앱, 어드민, 모바일 웹 및 공유 UI 라이브러리와 같은 여러 프런트엔드 프로젝트를 단일 Git 저장소에서 관리하며 일관된 의존성 그래프로 연결하는 구조입니다 [1, 2]. 이는 UI 원시(primitives), 디자인 토큰, 라우팅 규칙 등을 공유하는 다수의 애플리케이션 간의 일관성을 유지하는 데 필수적입니다 [2, 3]. 강력한 빌드 도구와 아키텍처 규칙(예: FSD)을 통해 모듈 간의 결합도를 낮추고 응집도를 높임으로써, 원자적 리팩터링(atomic refactors)을 지원하고 대규모 프런트엔드 플랫폼을 효율적으로 확장할 수 있게 합니다 [2, 4, 5].

📖 Core Content

• 아키텍처 원칙 및 경계 강제 (Boundaries & Public APIs): 확장 가능한 모노레포는 단순히 여러 폴더의 집합이 아니라, 강제된 경계와 명확한 의존성 방향을 가진 모듈 시스템입니다 [1, 6]. UI 컴포넌트 패키지가 내부 깊숙한 파일 경로로 직접 참조(deep imports)되는 것을 방지하기 위해, 패키지별로 단일 진입점(src/index.ts)을 통한 **명시적인 공개 API(Public API)**를 구성해야 합니다 [7-9]. 또한, 공유 UI 원시 요소(Shared UI primitives)는 상위 계층의 비즈니스 기능(Feature) 패키지를 절대 임포트하지 않도록 엄격한 **계층적 의존성(Layered Dependencies)**을 유지해야 합니다 [10, 11].

• 모노레포 도구 생태계 (Tooling in 2025): 대규모 UI 컴포넌트 환경에서 통합 비용과 빌드 시간을 줄이기 위해 전문화된 도구들이 사용됩니다.

  • pnpm workspaces: workspace:* 프로토콜을 사용하여 빠르고 공간 효율적이며 엄격한 로컬 패키지 의존성 연결을 보장합니다 [12, 13].
  • Turborepo: 가벼운 오케스트레이터로서 패키지 의존성 그래프를 존중하며, 점진적 빌드(incremental builds)와 원격 캐싱을 통해 파이프라인 속도를 크게 단축합니다 [13-15].
  • Nx: 대규모 조직에서 표준화된 가드레일이 필요할 때 사용하는 전체 모노레포 플랫폼입니다. 강력한 프로젝트 그래프를 기반으로 변경된(affected) 모듈만 빌드하고 테스트하며, 모듈 경계 정책을 코드 상에서 강제할 수 있습니다 [13, 16, 17].

• 기능 분할 설계 (Feature-Sliced Design, FSD): 프런트엔드 모노레포의 장기적인 성공을 위해 개별 앱 및 공유 패키지 내부에 기능 분할 설계(FSD) 방법론을 적용합니다 [5, 18]. FSD는 코드를 Shared, Entities, Features, Widgets, Pages, App 등의 계층으로 나누어 의존성이 한 방향으로만 흐르게 합니다 [19]. 이 접근 방식은 '공유(shared)' 폴더가 정돈되지 않은 쓰레기장이 되는 것을 방지하고, 재사용 가능한 도메인 패키지의 경계를 명확히 하여 온보딩 및 리팩터링의 안전성을 높입니다 [20-22].

• CI/CD 및 성능 최적화 (CI/CD & Caching): 대규모 컴포넌트 라이브러리를 공유할 때 모든 PR이 전체 시스템을 다시 빌드하게 하면 막대한 비용이 발생합니다 [2, 9]. 따라서 "영향을 받는(affected) 앱과 패키지만 빌드 및 배포한다"는 전략이 필수적입니다 [23, 24]. 원격 캐싱(Remote caching)을 활용하면 머신 간 빌드 결과물을 재사용할 수 있어, 공통 UI 패키지가 변경될 때 발생하는 피드백 루프와 연산 비용을 획기적으로 줄일 수 있습니다 [9, 25].

🔗 Knowledge Connections

• Related Topics: Feature-Sliced Design (FSD), Turborepo 및 Nx 빌드 시스템, Reusable UI Components, Design Tokens, React Server Components (RSC)
• Projects/Contexts: Uber의 Base Web 등 다양한 내부 앱 관리를 위한 디자인 시스템 도입, 확장 가능한 프런트엔드를 위한 의존성 및 패키지 구조화
• Contradictions/Notes: 모노레포 아키텍처는 코드 공유와 원자적 커밋의 이점을 제공하지만, "공유 모듈이 무분별하게 참조되는 스파게티 코드(spaghetti sharing)"를 유발할 위험이 있습니다. 소스에서는 이를 방지하기 위해 린트(Lint) 규칙, 엄격한 코드 소유권(CODEOWNERS), FSD와 같은 경계 강제가 없으면 오히려 통합 비용이 급증할 수 있다고 경고합니다 [1, 8, 26, 27]. 또한, 서로 코드를 공유할 필요가 거의 없는 완전히 독립적인 제품들의 경우 폴리레포(Polyrepo)가 더 안전한 선택이라고 조언합니다 [28].

---

Last updated: 2026-04-26