달레UI에게 스토리북은 중요할까?

스토리북은 UI 컴포넌트를 독립적인 환경에서 만들고, 테스트하고, 문서화할 수 있도록 도와주는 유용하고 강력한 도구입니다.
덕분에 전체 애플리케이션의 복잡한 로직에서 벗어나, 컴포넌트의 디자인과 상호작용, 다양한 상태 변화에만 온전히 집중할 수 있습니다.

무엇보다 스토리북은 컴포넌트를 재사용 가능한 단위로 정리하고, 일관된 UI를 시각적으로 검증할 수 있게 해줍니다.
이는 곧 디자인 시스템의 핵심 목표와 이어지며, 디자이너와 개발자에게 같은 기준을 공유해 효율적으로 협업할 수 있는 기반이 됩니다.

디자인 시스템을 목표로 하는 달레UI에게 스토리북은 단순한 개발 도구가 아닙니다.
누군가 달레UI를 쓸지 고민할 때 가장 먼저 보는 것은 스토리북 속 컴포넌트와 그 완성도입니다.
그래서 달레UI에게 스토리북은 프로젝트의 얼굴이자 소통 채널입니다.

스토리북과 더불어 애드온, 크로메틱은 이 글의 "개발과 소통의 중심: Storybook 생태계와 품질 관리" 부분을 참고하시면 좋습니다.

왜 Storybook v9으로 마이그레이션을 해야 했을까?

달레UI는 최신 기술 스택을 유지함으로써 기술 부채를 방지하고, 기여자들에게 쾌적한 개발 경험을 제공하는 오픈소스를 목표로 합니다. 그 노력의 일환으로 Dependabot을 활용해 꾸준히 의존성을 업데이트하고 있습니다.

이러한 철학의 연장선에서, 최근 메이저 업데이트가 발표된 Storybook v9로 마이그레이션을 결정했습니다. 단순히 최신 버전을 따라가는 것을 넘어, Storybook v9이 제공하는 번들 크기 감소, 핵심 기능 통합과 같은 구체적인 개선점들은 달레UI의 성능과 개발 효율성을 한 단계 더 끌어올릴 매력적인 기회였습니다.

성공적인 마이그레이션을 위한 전략은 무엇이었을까?

이번 마이그레이션의 핵심은 Storybook v9 환경에 맞게 관련 라이브러리를 업데이트 하는 것이었습니다.
마이그레이션 작업은 Storybook의 공식 마이그레이션 가이드 문서를 참고하여 진행했습니다.
오류 발생을 최소화하기 위해, 다른 의존성을 먼저 정리하고 Storybook 패키지 자체의 업데이트는 가장 마지막에 진행하는 전략을 선택했습니다.

Storybook v9으로 올라오면서 애드온 패키지들이 Storybook에 통합되거나 다른 패키지로 대체되었습니다. 이를 통해 달레UI는 애드온의 의존성과 불필요한 패키지를 발견해 덜어낼 수 있었습니다.

흡수된 패키지

아래 패키지들의 기능은 이제 Storybook v9의 코어에 내장되어 별도로 설치할 필요가 없어졌습니다.

• @storybook/addon-essentials
• @storybook/addon-interactions
• @storybook/theming

@storybook/addon-essentials, @storybook/addon-interactions

대체된 패키지

• @storybook/blocks → @storybook/addon-docs
  • Docs 기능이 @storybook/addon-docs로 통합되었습니다.
• @storybook/react → @storybook/react-vite
  • v9부터는 Vite 번들러에 특화된 프레임워크별 패키지를 사용하도록 변경되었습니다. 공식 문서에서 Svelte나 Vue의 경우 Vite 설정만 안내하는 것을 볼 때, Storybook이 Vite 중심으로 전환 중인 흐름을 확인할 수 있습니다.

달레UI에서 사용하지 않았던 패키지

초기 설정에는 포함되어 있었으나 실제 컴포넌트나 스토리에서 사용되지 않아 이번 기회에 의존성을 정리했습니다.

• @storybook/addon-links
• @storybook/test

Storybook v9 관련 패키지 업데이트

단순히 버전을 올리는 작업도 필요했습니다. v9과의 호환성을 맞추기 위해 아래 패키지들의 버전을 업데이트했습니다.

• @chromatic-com/storybook
• @storybook/addon-a11y
• @storybook/addon-designs
• @storybook/addon-themes
• @storybook/test-runner

특히 @storybook/test-runner의 경우, 초기에 의존성 충돌 문제가 있었지만 최신 버전으로 업데이트하며 간단히 해결할 수 있었습니다.

마이그레이션을 통해 무엇을 얻었을까?

마이그레이션을 통해 달레UI는 몇 가지 의미 있는 성과를 얻을 수 있었습니다.

첫째, 번들 크기와 파일 수가 감소했습니다.

가장 눈에 띄는 성과는 빌드된 Storybook의 번들 크기가 7.6MB에서 7.1MB로 줄고, 파일 개수 또한 감소했다는 점입니다. 수치상으로는 작아 보일 수 있지만, 불필요한 의존성을 덜어내고 프로젝트를 더 가볍게 만들었다는 점에서 긍정적인 결과입니다.

둘째, 코드가 일관성을 갖추게 되었습니다.

기존에 composeStories함수에서 타입 추론이 제대로 동작하지 않아 발생했던 일부 스토리 코드의 비일관성 문제도 해결되었습니다. 이번 업데이트로 타입 안정성이 향상되어 더 일관된 코드 작성이 가능해졌습니다.

셋째, 예상치 못한 제약사항을 해결했습니다.

마이그레이션 과정에서 Storybook v9이 Node.js v20 이상을 요구한다는 기술적 제약사항을 발견했습니다. 저희 프로젝트는 Bun을 사용하지만, storybook 실행 명령어는 시스템의 Node.js 버전에 의존하기에 이 문제를 해결해야 했습니다.

팀 논의 끝에, package.json의 engines 필드로 버전을 강제하기보다는, 버전이 맞지 않을 경우 Storybook이 출력하는 명확한 에러 메시지에 의존하기로 결정했습니다. 이는 특정 버전을 강제하기보다, 명확한 에러 메시지를 통해 개발자가 직접 문제를 인지하고 대처하도록 하는 유연한 방식이라고 판단했습니다.

물론 아쉬운 점도 있었습니다.
내심 기대했던 Docs의 다크 모드 자동 적용은 이루어지지 않아, 기존의 커스텀 코드를 그대로 유지해야 했습니다. 이는 향후 개선 과제로 남겨두었습니다.

이번 마이그레이션은 단순히 라이브러리 버전을 올리는 것을 넘어, 달레UI 프로젝트의 의존성 구조를 되돌아보고 최적화하는 좋은 기회였습니다. 이번 경험을 바탕으로, 앞으로도 정기적인 의존성 검토와 업데이트를 통해 프로젝트를 최적의 상태로 유지해 나갈 계획입니다. 앞으로도 저희 달레UI는 꾸준한 개선을 통해 더 나은 디자인시스템이 되겠습니다.

This work is licensed under CC BY 4.0 cc xlarge by xlarge