모노레포 기반 디자인 시스템 패키지 구축기

안녕하세요. 노머스에서 fromm 프론트엔드 개발을 하고 있는 지수민입니다.

이번 글에서는 모노레포 환경에서 디자인 시스템 패키지를 구축하게 된 과정과 구축하면서 고민했던 부분들을 공유해보려고 합니다.

배경

현재 프론트엔드 팀은 하나의 저장소(레포지토리) 안에서 여러 서비스를 동시에 개발하는 모노레포(monorepo) 방식을 사용하고 있습니다. 모노레포 적용 과정에 대한 자세한 내용은 프론트엔드 모노레포 적용기 기술 블로그를 참고하실 수 있습니다.

개발하는 서비스로는 아티스트 굿즈를 판매하는 프롬스토어(fromm store)와, 아티스트와 팬들이 소통할 수 있는 프롬채널(fromm channel)이 있습니다.

두 서비스는 동일한 디자인을 기반으로 만들어졌기 때문에, 전반적인 UI 구성과 스타일이 매우 유사합니다. 하지만 각 서비스에서는 공통된 컴포넌트들을 따로 구현해서 사용하고 있는 상황이었습니다. 예를 들어 Button, Input 같은 가장 기본적인 UI 요소조차 중복으로 작성되고 있었습니다.

이러한 구조는 시간이 지날수록 유지보수 비용을 높이고, 디자인이 변경될 때마다 각각 수정해야 하는 번거로움이 존재했습니다.

그래서 우리는 모노레포 구조를 활용하여 공통 UI 컴포넌트를 하나의 디자인 시스템 패키지로 정리하고 각 서비스에서 이를 설치해서 사용하는 방식으로 개선하고자 했습니다.

모노레포 패키지와 디자인 시스템 구축

디자인 시스템 패키지 구성

우리팀이 선택한 방법은, 모노레포 안에 새로운 패키지를 하나 추가해 모든 공통 컴포넌트를 이 패키지 안에서 관리하는 방식이었습니다.

packages 디렉터리 안에 /@packages/fds(Fromm Design System) 패키지를 새로 만들고, 그 안에 공통 버튼, 다이얼로그 등 다양한 컴포넌트를 개발했습니다.

📦 fds
┣ 📂 .storybook         
┣ 📂 src                 
┃ ┣ 📂 components        
┃ ┃ ┣ 📂 molecules       
┃ ┃ ┃ ┗ 📂 Button        
┃ ┃ ┣ 📂 organisms       
┃ ┃ ┃ ┗ 📂 Dialog        
┃ ┣ 📂 foundations       
┃ ┗ 📂 utils             
┣ 📂 tokens              
┗ 📄 package.json        

각 서비스(프롬스토어, 프롬채널)는 이 디자인 시스템 패키지를 설치하여 공통 컴포넌트를 사용할 수 있도록 구성했습니다. 즉, 더 이상 서비스마다 같은 컴포넌트를 별도로 구현할 필요가 없게 된 것입니다.

설치 방식

공통 패키지를 사용할 수 있는 방법은 두 가지가 있습니다.

• 패키지를 NPM 같은 외부 레지스트리에 배포한 후 설치하는 방법
• 모노레포 내부에서 패키지를 직접 참조해 설치하는 방법

우리는 두 번째 방법인 모노레포 내 로컬 패키지 방식 을 선택했습니다.

외부로 배포하는 방식도 고려했지만, 다음과 같은 이유로 내부 패키지 방식을 선택하게 되었습니다.

• 현재는 사내 프로젝트에 한정해 사용되기 때문에 외부 배포까지는 필요하지 않았습니다.
• 버전 관리와 업데이트 주기를 더 유연하고 빠르게 가져갈 수 있었습니다.
• 모노레포 관리 도구(Turborepo)를 활용해 패키지 의존성 관리를 효율적으로 할 수 있었습니다.

모노레포 구조

우리 프로젝트의 모노레포 구조는 다음과 같이 구성되어 있습니다.

📦 fromm-web
┣ 📂 apps
┃ ┣ 📂 store        # 프롬스토어 서비스
┃ ┗ 📂 channel      # 프롬채널 서비스
┣ 📂 packages
┃ ┗ 📂 fds          # 프롬 디자인 시스템 (Fromm Design System)

• /apps 디렉터리에는 실제 서비스 애플리케이션이 들어 있고
• /packages 디렉터리에는 공통 패키지들이 존재합니다.

서비스에서는 디자인 시스템을 workspace로 설치해서 사용합니다.

pnpm add @packages/fds

모노레포 내부 연결(workspace)을 통해 별도의 외부 배포 없이도 빠르게 개발을 이어갈 수 있게 되었습니다.

고려한 점

디자인 시스템을 구축하면서 가장 신경 쓴 부분은 기존 공통 컴포넌트와의 분리였습니다.

과거에 작성했던 공통 컴포넌트는 서비스별로 커스텀된 로직이나 스타일이 섞여 있어서, 새로운 디자인 시스템은 최대한 독립적이고 표준화된 형태로 다시 개발해야 했습니다.

또한, 개발 과정에서 디자이너, 개발자 분들과 함께 커뮤니케이션하며, 명확한 디자인 가이드를 문서화하는 작업도 함께 진행했습니다.

디자인 시스템 스토리북

디자인 시스템 패키지를 구축한 이후, 스토리북(Storybook) 을 적용해 컴포넌트를 문서화했습니다.

스토리북은 단순히 팀 내 개발자 간 공유를 넘어서, 디자이너와 기획자 분들도 직접 확인하여 컴포넌트 간 UI 통일성을 유지하고, 빠른 피드백을 받을 수 있도록 배포했습니다.

현재는 스토리북을 빌드한 후, AWS S3에 수동으로 업로드하여 배포하고 있습니다. 향후에는 커밋과 동시에 서버에 최신 버전이 자동 반영될 수 있도록 CI/CD 자동화를 구축할 계획입니다. 이를 통해 배포 과정을 더욱 간편하고 효율적으로 개선해나갈 예정입니다.

마치며

이번 모노레포 디자인 시스템 구축 프로젝트를 통해, 우리 서비스 개발 속도를 높이고, 공통 UI 컴포넌트 관리의 일관성을 확보할 수 있게 되었습니다.

특히, 버튼처럼 아주 기본적인 컴포넌트 하나까지도 디자인 시스템 안에서 일관성 있게 관리할 수 있다는 점이 큰 의미였습니다.

앞으로, 꾸준히 디자인 시스템을 고도화하고, 다른 패키지들과의 의존성 문제를 개선해 나가면서 더 나은 개발 경험을 만들어 나가려고 합니다.

감사합니다!