MultiRepo MFE Boilerplate 개요
소개
MultiRepo-MFE-Boilerplate는 멀티레포(Multi-repository) 환경에서 Module Federation을 활용하여 구성된 마이크로 프론트엔드(Micro Frontend, MFE) 프로젝트입니다.
본 보일러플레이트는 React와 TypeScript를 기반으로 하며, 재사용 가능한 UI 컴포넌트, 유틸리티 라이브러리, 그리고 데모 플랫폼을 통합 제공합니다.
특히, Module Federation 기술을 활용하여 독립적으로 개발 및 배포가 가능한 복수의 애플리케이션을 하나의 Shell(Host) 애플리케이션 내에서 유기적으로 통합하는 마이크로 프론트엔드 아키텍처를 실현합니다.
참조
- 모노레포, 멀티레포란, 모놀리식이란? - ../config-strategy/repository-config-strategy
- 마이크로 프론트엔드(MFE)란? - ../config-strategy/micro-frontend
- Module Federation - ../config-strategy/module-federation
- 마이크로 프론트엔드 구성 전략 PDF - http://redsky0212.dothome.co.kr/2026/slide/mf02.pdf
MultiRepo MFE(마이크로 프론트엔드)란 무엇인가? 소개자료
주요 목적
- 빠른 멀티레포 프로젝트 셋업: 멀티레포 + 마이크로 프론트엔드 아키텍처를 처음부터 구성하는 데 드는 복잡한 초기 설정을 생략하고, 각 레포지토리별로 검증된 프로젝트 구조를 그대로 가져다 비즈니스 로직 개발에 바로 집중할 수 있습니다.
- 멀티레포 MFE 아키텍처 레퍼런스 제공: 각 애플리케이션이 독립된 레포지토리로 분리된 Module Federation 기반의 Host(Shell)/Remote 앱 구조를 실제 동작하는 예제로 제공하여, 팀이 멀티레포 마이크로 프론트엔드 패턴을 빠르게 이해하고 적용할 수 있도록 합니다.
- 독립적 개발·배포 환경 지원: 각 Remote 앱이 별도의 레포지토리로 완전히 분리되어 있어, 팀별·도메인별로 독립적인 개발 주기, CI/CD 파이프라인, 배포 전략을 가져갈 수 있습니다.
- 공유 라이브러리(Shared Library) NPM 패키지 연동: shadcn/ui 기반 UI 컴포넌트, 유틸리티 함수, 커스텀 훅(Hooks), 전역 Context, 공통 타입 정의 등을 별도 레포지토리의 NPM 패키지로 배포하여 모든 멀티레포 앱에서 일관되게 재사용할 수 있습니다.
- 일관된 개발 환경 및 코드 품질 보장: ESLint, Prettier, TypeScript 설정을 공유 라이브러리 패키지에서 통합 관리하여 멀티레포 내 모든 앱에 동일한 코드 스타일과 품질 기준을 적용합니다.
- 컴포넌트 문서화 및 카탈로그 제공: Storybook을 통해 공유 컴포넌트의 인터랙티브 데모와 사용 예제를 제공하고, Docusaurus 기반 문서 사이트를 통해 멀티레포 아키텍처 가이드와 개발 가이드를 체계적으로 문서화합니다.
- 확장 가능한 멀티레포 구조 제시: 새로운 Remote 앱을 별도 레포지토리로 독립적으로 추가·개발·배포할 수 있는 확장 가능한 구조를 제시하여, 팀이나 도메인이 늘어나도 각 레포지토리의 자율성을 유지하면서 일관된 방식으로 프로젝트를 성장시킬 수 있습니다.
- 개발 생산성 향상: 반복적인 초기 설정, 공통 컴포넌트 재개발, 개발 환경 구성 등에 소요되는 시간을 줄이고, 레포지토리 간 충돌 없이 실제 비즈니스 기능 개발에 더 많은 리소스를 집중할 수 있습니다.
제공 UI 컴포넌트
현재 제공되는 주요 컴포넌트는 다음과 같습니다. (계속 추가 중)
- Accordion: 접이식 콘텐츠 패널
- Alert & AlertDialog: 알림 및 확인 다이얼로그
- Badge: 상태 표시 배지
- Button: 다양한 스타일의 버튼
- Calendar: 날짜 선택 캘린더
- Checkbox: 체크박스 입력
- Dialog: 모달 다이얼로그
- Icon: 아이콘 컴포넌트
- Input: 텍스트 입력 필드
- Select: 드롭다운 선택
- Spinner: 로딩 스피너
- Table: 데이터 테이블
제공 유틸리티
현재 제공되는 주요 유틸리티는 다음과 같습니다. (지속적으로 추가 중)
- API Helper: Axios 기반의 API 통신 함수 및 공통 request/error 핸들러
- Date Utils: 날짜 포맷 변환, 상대 날짜 계산 등 날짜 처리 함수
- Array/Object Utils: 배열, 객체 조작을 위한 다양한 헬퍼 함수 (정렬, 필터, 딥 클론 등)
- Data Formatter: 통화, 숫자, 퍼센트 등 각종 데이터 포맷 변환 함수
- Validation Utils: 이메일, 휴대폰 번호, 숫자 등 다양한 입력값 유효성 검사 함수
- Storage Utils: 로컬스토리지, 세션스토리지 편의 함수
- String Utils: 문자열 변환, 치환, 대소문자 변경 관련 함수
- Clipboard Utils: 텍스트, 객체 클립보드 복사 함수 및 지원 여부 체크
장점
개발 생산성 향상
- 즉시 사용 가능한 UI 컴포넌트: 자주 사용하는 UI 컴포넌트를 Shared Library에서 바로 import하여 사용할 수 있어 개발 시간을 크게 단축할 수 있습니다. 또한, 프로젝트 상황에 맞게 스타일의 유연성과 커스터마이징 용이성 측면에서도 매우 큰 장점이 있습니다.
- 일관된 디자인 시스템: 통일된 디자인 가이드라인을 따르는 컴포넌트로 모든 Remote 앱에서 일관성 있는 UI를 구축할 수 있습니다.
- 반복 설정 제거: 멀티레포 + MFE 아키텍처의 복잡한 초기 설정을 이미 구성해 두었으므로, 팀은 비즈니스 로직 개발에 바로 집중할 수 있습니다.
- Storybook 기반 컴포넌트 카탈로그: 각 컴포넌트마다 인터랙티브 데모와 코드 예제를 제공하여 학습 곡선을 낮추고 개발 생산성을 향상시킵니다.
타입 안정성
- TypeScript 기반: 모든 컴포넌트와 유틸리티 함수가 TypeScript 5.9로 작성되어 타입 안정성을 보장합니다.
- 명확한 타입 정의: 컴포넌트 props와 반환값에 대한 명확한 타입 정의로 개발 시 오류를 사전에 방지합니다.
- IDE 자동완성 지원: TypeScript의 강력한 타입 시스템으로 IDE(VSCode)에서 자동완성과 타입 체크를 제공합니다.
- 공유 타입 패키지:
@axiom/mfe-lib-shared/types를 통해 Host와 모든 Remote 앱이 동일한 타입 정의를 공유합니다.
접근성 (Accessibility)
- Base UI 기반: 비스타일(unstyled) 접근성 기반 컴포넌트 라이브러리인 Base UI를 활용하여 접근성 표준을 준수합니다.
- shadcn/ui 통합: shadcn/ui 기반의 재사용 가능한 UI 컴포넌트를 함께 제공하여 빠른 개발과 높은 접근성을 동시에 확보합니다.
- 키보드 네비게이션: 모든 컴포넌트가 키보드로 완전히 조작 가능합니다.
- 스크린 리더 지원: ARIA 속성을 적절히 사용하여 스크린 리더 사용자를 지원합니다.
커스터마이징 용이성
-
Tailwind CSS v4 기반: 최신 Tailwind CSS를 사용하여 스타일을 쉽게 커스터마이징할 수 있습니다.
-
유연한 스타일링: 공유 CSS 토큰(Design Token)과 Base 스타일을 기반으로, 각 Remote 앱에서 독립적인 스타일을 자유롭게 적용할 수 있습니다.
-
헤드리스 컴포넌트 방식: 기존에 널리 사용되는 UI 프레임워크(MUI, AntD, Chakra UI)의 컴포넌트가 아닌, 헤드리스 컴포넌트 방식을 도입하여 프로젝트 상황에 맞게 자유롭게 수정하고 확장할 수 있습니다.
헤드리스 컴포넌트란?헤드리스 컴포넌트는 사용자 인터페이스(UI) 없이 컴포넌트의 핵심 기능 로직과 상태 관리만을 담당하는 디자인 패턴입니다. 말 그대로 '머리(Head, 즉 시각적인 UI)'가 없는 컴포넌트입니다.
UI 구현은 외부에 위임하며, 개발자는 이 헤드리스 컴포넌트가 제공하는 로직과 상태를 활용하여 자신만의 커스텀된 UI를 자유롭게 만들 수 있습니다.
현대적인 아키텍처
- Module Federation (MFE) - 멀티레포 통합:
@module-federation/vite를 활용하여 별도 레포지토리에서 관리되는 Host(Shell) 앱과 여러 Remote 앱을 각자 독립적으로 개발·배포하고, 런타임에 동적으로 통합합니다. - 레포지토리 단위 독립 배포: 각 Remote 앱이 독립된 레포지토리로 분리되어 있어, 팀별로 자체적인 빌드·배포 파이프라인(CI/CD)을 구성하고 다른 팀과 무관하게 독립적으로 릴리즈할 수 있습니다.
- React Router v7: SPA(Single Page Application) 기반의 라우팅을 제공하며, 각 Remote 앱은 독립된 레포지토리 내에서 자체적인 라우팅 구조를 가집니다.
- 도메인 기반 구조(DDD): 팀 또는 업무 도메인 단위로 레포지토리 자체를 분리하여 소스코드의 복잡도와 레포지토리 간 충돌을 원천 차단하고, 유지보수성과 확장성을 크게 향상시켰습니다.
- Singleton 공유 라이브러리 (NPM 패키지):
react,react-router,zustand,@tanstack/react-query등 핵심 라이브러리를 별도 레포지토리에서 NPM 패키지로 배포·관리하여 Host와 Remote 간 중복 인스턴스 문제를 방지합니다. - 레포지토리 독립 확장 구조: 새로운 Remote 앱을 신규 레포지토리로 독립 생성하여 기존 앱에 영향 없이 언제든지 추가·확장할 수 있습니다.
상태 관리
- Zustand 통합: 경량 전역 클라이언트 상태 관리 라이브러리로, 보일러플레이트 없이 간결하게 전역 상태를 정의하고 공유할 수 있습니다.
- TanStack Query (React Query) 통합: 서버 상태 관리를 위한 강력한 라이브러리로 데이터 페칭, 캐싱, 동기화를 자동으로 처리합니다.
- 자동 캐싱 및 리페칭: API 응답을 자동으로 캐싱하고 백그라운드에서 데이터를 최신 상태로 유지합니다.
- 낙관적 업데이트: UI를 즉시 업데이트하고 백그라운드에서 서버와 동기화하여 빠른 사용자 경험을 제공합니다.
- API 통합 지원: Axios 기반의 공통 API 클라이언트를 제공하여 백엔드와의 통신을 간소화합니다.
성능 최적화
- Vite 7 기반 초고속 빌드: 네이티브 ES 모듈 기반의 Vite를 사용하여 개발 서버 시작 및 HMR(Hot Module Replacement) 속도를 극대화합니다.
- Module Federation 지연 로딩: Remote 앱은 실제로 접근할 때 동적으로 로드되어 초기 번들 크기를 최소화하고 로딩 성능을 향상시킵니다.
- 자동 코드 스플리팅: Vite의 Rollup 기반 빌드를 통해 페이지 및 모듈 단위 코드 스플리팅이 자동으로 적용됩니다.
- Remote 에러 격리:
RemoteErrorBoundary,RemoteLoadingFallback,RemoteOfflineFallback컴포넌트를 통해 특정 Remote 앱의 장애가 전체 앱에 영향을 미치지 않도록 격리합니다.
개발자 경험 (DX)
- Storybook 기반 컴포넌트 문서: UI 컴포넌트를 직접 조작해보며 동작을 확인할 수 있는 인터랙티브 카탈로그를 제공합니다.
- Docusaurus 기반 가이드 문서: 아키텍처 설계 의도, 개발 가이드, 온보딩 문서를 체계적으로 제공합니다.
- 통합 코드 품질 관리: ESLint, Prettier 설정을 Shared Library에서 통합 관리하여 모노레포 내 모든 앱에 동일한 코드 스타일과 품질 기준을 적용합니다.
- 빠른 개발 환경: Vite의 초고속 HMR로 코드 변경 시 즉각적인 피드백 루프를 제공합니다.
기반 기술
핵심 프레임워크 및 라이브러리
| 기술 | 버전 | 설명 |
|---|---|---|
| React | ^19.2 | UI 라이브러리 |
| TypeScript | ~5.9 | 정적 타입 언어 |
| Vite | ^7 | 빌드 도구 및 개발 서버 |
| @module-federation/vite | ^1.11 | Vite 기반 Module Federation (멀티레포 런타임 통합) |
| pnpm | ^10 | 각 레포지토리별 독립 패키지 관리자(필요 시에만 사용) |
| NPM Registry | - | Shared Library를 NPM 패키지로 배포·버전 관리 |
UI 프레임워크 및 스타일링
| 기술 | 버전 | 설명 |
|---|---|---|
| TailwindCSS | ^4 | 유틸리티 기반 CSS 프레임워크 |
| shadcn/ui | - | 재사용 가능한 UI 컴포넌트 |
| Base UI | ^1.1 | 비스타일 접근성 기반 헤드리스 컴포넌트 |
| Lucide React | ^0.563 | 아이콘 라이브러리 |
| Inter (Variable Font) | ^5.2 | 기본 폰트 |
| class-variance-authority | ^0.7 | 컴포넌트 변형(variant) 관리 |
| clsx + tailwind-merge | - | 조건부 클래스명 병합 처리 |
상태 관리 및 데이터 패칭
| 기술 | 버전 | 설명 |
|---|---|---|
| Zustand | ^5.0 | 전역 클라이언트 상태 관리 |
| TanStack Query | ^5.0 | 서버 상태 관리 및 비동기 데이터 패칭 |
| Axios | ^1.13 | HTTP 클라이언트 |
| react-helmet-async | ^2.0 | 동적 <head> 메타 태그 관리 |
라우팅
| 기술 | 버전 | 설명 |
|---|---|---|
| React Router | ^7.13 | SPA 클라이언트 사이드 라우팅 |
개발 도구
| 기술 | 설명 |
|---|---|
| ESLint | 코드 품질 검사 (Shared Library NPM 패키지에서 설정 통합 관리, 각 레포에서 extend하여 사용) |
| Prettier | 코드 포맷팅 (Shared Library NPM 패키지에서 설정 통합 관리, 각 레포에서 extend하여 사용) |
| Storybook | Shared Library 레포지토리에서 UI 컴포넌트 인터랙티브 개발 및 문서화 |
| Docusaurus | 멀티레포 아키텍처 및 개발 가이드 문서 사이트 (별도 레포지토리로 관리) |
| GitHub Actions / CI/CD | 각 레포지토리별 독립 빌드·테스트·배포 파이프라인 구성 |
프로젝트 구조
멀티레포 환경에서는 각 애플리케이션과 패키지가 독립된 Git 레포지토리로 분리됩니다.
레포지토리 구성
[GitHub Organization: multirepo-mf-boilerplate]
│
├── 🔗 multirepo-mf-shared-library # 공유 라이브러리 (NPM 패키지로 배포·버전 관리)
├── 📖 multirepo-mf-storybook # 컴포넌트 Storybook (독립 레포)
├── 📄 multirepo-mf-docs # 문서 사이트 Docusaurus (독립 레포)
├── 🏠 multirepo-mf-main # Host(Shell) 앱 — port 5000
├── 📦 multirepo-mf-remote1 # Remote App 1 — port 5001
├── 📦 multirepo-mf-corporate # Corporate Remote App — port 5002
├── 📦 multirepo-mf-asset-management # Asset Management Remote App — port 5003
└── 📦 multirepo-mf-retirement-pension # Retirement Pension Remote App — port 5004
각 앱 레포지토리 내부 구조 (DDD 기반)
각 Host/Remote 앱 레포지토리는 DDD(Domain Driven Design) 기반의 도메인 분리 구조를 따릅니다.
도메인별로 소스코드를 분리하여 의존성을 최소화하고, 팀 간 충돌을 방지하며 확장성을 높입니다.
multirepo-mf-main/ (각 Remote 앱 레포도 동일한 구조)
├── src/
│ ├── app/ # 앱 전체 공통 영역 (공통 개발자 관리 영역)
│ │ ├── api/ # 공통 API 클라이언트 설정
│ │ ├── components/ # 앱 공통 컴포넌트 (레이아웃, 헤더 등)
│ │ ├── router/ # 전체 라우팅 설정
│ │ └── store/ # 전역 상태 관리 (Zustand)
│ ├── assets/ # 정적 파일 (fonts, images, css)
│ ├── domains/ # 업무 도메인별 분리 (DDD) — 업무 개발자 작업 영역
│ │ ├── home/ # 홈 도메인
│ │ │ ├── api/ # REST API URL 및 request/response 타입 정의
│ │ │ ├── components/ # 도메인 전용 컴포넌트
│ │ │ ├── pages/ # 화면 파일 (*.tsx)
│ │ │ ├── router/ # 도메인 라우팅
│ │ │ ├── store/ # 도메인 상태 관리
│ │ │ └── types/ # 도메인 타입 정의
│ │ └── [domain]/ # 업무 도메인 추가·확장
│ ├── App.tsx
│ └── main.tsx
├── package.json # 독립 의존성 관리 (pnpm)
├── vite.config.ts # Vite + Module Federation 설정
└── ... # ESLint, Prettier, tsconfig 등 (Shared Library에서 extend)
각 레포지토리는 독립적으로 개발·빌드·배포되며, 공통으로 필요한 컴포넌트·훅·유틸리티·타입·설정은 multirepo-mf-shared-library NPM 패키지를 package.json에 의존성으로 추가하여 공유합니다.