BUILT & IMPROVED · 2025.02 — 03

Nuxt 모노레포에
Storybook 개발 환경 구축

공통 설정을 공유하는 단순한 구조로 시작했지만, Nuxt 런타임과 Storybook의 독립 빌드 환경이 충돌했습니다. 네 가지 대안을 검증한 뒤 패키지별 구성을 선택했습니다.

개발 환경 구축기술 대안 검증모노레포 구조 개선
문제
스타일·Auto Imports 미동작
판단
공통 설정보다 실행 안정성
결과
패키지별 Storybook 구축
01

배경

여러 Nuxt 패키지의 UI를 독립적으로 개발하고 검증할 환경이 필요했습니다. 초기에는 유지보수 비용을 줄이기 위해 모노레포 루트에 Storybook 설정을 두고 모든 패키지가 공유하도록 구성했습니다.

그러나 Storybook은 Nuxt 애플리케이션과 별도로 빌드되기 때문에 Tailwind 설정, 사내 디자인 시스템, Nuxt Auto Imports가 자동으로 이어지지 않았습니다.

02

검토한 대안

편의성만으로 도구를 선택하지 않고, 당시 프로젝트의 pnpm 모노레포 구조에서 실제로 실행되는지 확인했습니다.

  1. Nuxt용 Storybook 애드온보류

    기존 Vite 설정과 함께 적용했지만 화면이 정상적으로 렌더링되지 않았고, 원인을 추적할 단서도 충분하지 않았습니다.

  2. Nuxt 전용 Storybook 프레임워크부분 성공

    단독 패키지에서는 Auto Imports가 동작했지만, 루트의 공통 설정에서 실행할 때 메모리 사용량이 급증했습니다.

  3. Nuxt tsconfig 확장보류

    타입 정보는 연결할 수 있었지만 Storybook 런타임에는 실제 구현이 주입되지 않아 컴포넌트를 실행할 수 없었습니다.

  4. Nuxt 빌드 산출물 직접 참조보류

    타입 선언과 번들된 런타임 산출물의 구조가 달라 안정적인 연결 방식으로 사용하기 어려웠습니다.

03

결정

공통 설정이 주는 관리 편의보다 Nuxt 런타임을 억지로 공유할 때 생기는 결합 비용이 더 크다고 판단했습니다. 설정의 중복을 일부 감수하고, Storybook이 필요한 패키지 안에 설정을 두는 구조로 전환했습니다.

BEFORE루트 공통 설정낮은 중복 · 높은 런타임 결합
AFTER패키지별 설정명시적 구성 · 안정적인 실행
04

결과

  • Nuxt Auto Imports를 사용하는 컴포넌트를 별도 설정 없이 Storybook에서 렌더링
  • Tailwind와 사내 디자인 시스템을 실제 서비스와 유사한 조건으로 확인
  • 반응형 뷰포트와 사용자 환경을 툴바에서 전환하며 컴포넌트 상태를 검증

이 작업을 통해 ‘설정을 얼마나 많이 공유하는가’보다 ‘각 도구가 기대하는 실행 경계를 얼마나 명확하게 지키는가’가 모노레포의 유지보수성에 더 중요할 수 있음을 배웠습니다.