들어가며
이번에 큐시즘 기업프로젝트에 참여하게 되었다. 프론트엔드 개발을 맡으면서 여러 UI 컴포넌트를 만들어야 하는 상황이었는데, 개발을 시작하기 전에 한 가지 고민이 생겼다.
"컴포넌트를 하나 확인하려면 매번 앱 전체를 실행해야 하나?"
버튼 컴포넌트 하나를 수정했을 때, 그 결과를 보려면 앱을 띄우고, 해당 페이지로 이동하고, 특정 조건을 만족시켜야 할 수도 있다. 단순히 버튼의 색상이 바뀌었는지 확인하는 데도 꽤 번거로운 과정이 필요한 셈이다.
거기에 더해 이런 불편함들도 떠올랐다.
- 다양한 상태를 확인하기 어렵다: 버튼 하나만 해도 기본, 호버, 비활성화, 로딩 중 등 다양한 상태가 있는데, 이걸 앱 안에서 일일이 재현하려면 꽤 귀찮다.
- 팀원과 UI를 공유하기 어렵다: "이 컴포넌트 이렇게 만들었는데 어때?"라고 보여주려면 로컬 서버를 같이 띄우거나 스크린샷을 찍어야 한다.
- 문서화가 따로 논다: 컴포넌트를 만들어놓고 "이 컴포넌트는 이런 props를 받고, 이런 상태가 있어"를 별도로 정리하는 건 솔직히 잘 안 하게 된다.
이런 고민을 하다가 Storybook이라는 도구를 알게 되었다.
Storybook 공식 사이트에 들어가면 이런 문구가 나온다.
Build, test & document components
Storybook is a frontend workshop for building UI components and pages in isolation.
핵심은 "in isolation", 즉 격리된 환경이다.
Storybook은 앱 전체를 실행하지 않고도 UI 컴포넌트를 하나하나 독립적으로 렌더링하고, 테스트하고, 문서화할 수 있는 프론트엔드 워크숍 도구다. 앱과 나란히 존재하는 별도의 개발 환경이라고 생각하면 된다.
좀 더 쉽게 비유하자면
- 앱 안에서 개발하는 것 = 완성된 자동차를 운전하면서 엔진 부품을 교체하는 것
- Storybook에서 개발하는 것 = 정비소에서 엔진 부품만 따로 꺼내서 점검하고 테스트하는 것
Storybook이라는 정비소에서 부품(컴포넌트)을 하나씩 꺼내서 다양한 조건에서 테스트해보고, 문제가 없으면 자동차(앱)에 다시 조립하는 워크플로우인 셈이다.
왜 격리된 환경에서 개발해야 할까?
공식 문서의 Why Storybook? 페이지를 읽어보면, 이런 문장이 나온다.
Every piece of UI is now a component. The superpower of components is that you don't need to spin up the whole app just to see how they render.
모든 UI가 컴포넌트로 이루어진 시대에, 컴포넌트의 진짜 강점은 앱 전체를 띄우지 않고도 렌더링 결과를 확인할 수 있다는 것이다. Storybook은 바로 이 강점을 극대화해주는 도구라고 이해했다. 앱과 별도의 격리된 환경(iframe)을 제공해서, 비즈니스 로직이나 컨텍스트의 간섭 없이 컴포넌트 자체에만 집중할 수 있게 해준다.
구체적으로 Storybook이 격리된 환경을 제공함으로써 얻는 이점들을 정리하면 이렇다.
1. 앱의 비즈니스 로직에 방해받지 않는다
Storybook은 앱과 별도의 iframe에서 컴포넌트를 렌더링한다. 즉, 앱의 라우팅, 상태 관리, API 호출 같은 것들이 컴포넌트 렌더링에 영향을 주지 않는다. 순수하게 "이 컴포넌트에 이 props를 주면 어떻게 보이는가?"에만 집중할 수 있다.
2. 재현하기 어려운 상태도 쉽게 확인할 수 있다
앱 안에서는 에러 상태, 로딩 상태, 빈 데이터 상태 같은 엣지 케이스를 재현하기가 까다롭다. 하지만 Storybook에서는 그냥 해당 상태의 props를 넘기면 된다. "에러가 났을 때 이 컴포넌트는 어떻게 보이지?"를 확인하기 위해 서버를 일부러 멈출 필요가 없다.
3. 개발과 동시에 테스트와 문서화가 된다
Storybook에서 작성하는 하나의 Story가 개발 도구이자, 테스트 케이스이자, 문서 역할을 한다.
Storybook의 4가지 핵심 가치
Storybook 공식 홈페이지를 보면 크게 4가지 가치를 내세우고 있다.
Development
컴포넌트와 페이지를 앱과 독립적으로 개발할 수 있다. 데이터, API, 비즈니스 로직을 신경 쓸 필요 없이 UI 자체에만 집중한다. Storybook의 사이드바에서 컴포넌트를 선택하고, Controls 패널에서 props를 실시간으로 바꿔보면서 다양한 상태를 확인할 수 있다. 앱을 실행하지 않아도 "이 props를 주면 어떻게 보이지?"를 바로 확인할 수 있는 것이 핵심이다.
Interaction Testing
사용자의 행동을 코드로 시뮬레이션해서 컴포넌트가 제대로 동작하는지 테스트할 수 있다. 예를 들어 "이메일 입력 → 비밀번호 입력 → 제출 버튼 클릭 → 성공 메시지 표시"라는 흐름을 play function이라는 기능으로 자동화할 수 있다. Storybook의 Interactions 패널에서 각 단계를 하나씩 확인하고 디버깅하는 것도 가능하다.
Visual Testing
UI가 의도하지 않게 바뀌었는지를 픽셀 단위로 감지하는 기능이다. 코드를 수정한 후 기존 Story와 비교해서 시각적인 변경점을 찾아준다. "분명 다른 컴포넌트만 수정했는데 이 컴포넌트의 레이아웃이 깨졌네?" 같은 상황을 자동으로 잡아낼 수 있다.
Documentation
컴포넌트의 props 정보와 Story를 기반으로 문서를 자동 생성해준다. 컴포넌트가 어떤 props를 받는지, 각 상태가 어떻게 보이는지를 따로 정리하지 않아도 Story만 잘 작성하면 문서가 만들어진다. Markdown/MDX로 커스텀 설명을 추가할 수도 있어서, 디자인 시스템 문서화에도 활용된다.
Component-Driven Development
Storybook을 사용하는 팀들이 주로 따르는 개발 방식이 있다. 바로 Component-Driven Development(CDD), 즉 컴포넌트 주도 개발이다.
쉽게 말하면 "바텀업" 방식으로 UI를 만드는 것이다.
1. 작은 컴포넌트를 격리된 환경에서 하나씩 만든다
(Button, Input, Badge 같은 기본 단위)
↓
2. 작은 컴포넌트를 조합해서 더 복잡한 컴포넌트를 만든다
(SearchBar = Input + Button, Card = Image + Badge + Button)
↓
3. 복합 컴포넌트를 조합해서 페이지를 구성한다
(ProductPage = Header + SearchBar + CardList + Footer)
↓
4. 페이지에 데이터와 비즈니스 로직을 연결한다
(API 호출, 상태 관리, 라우팅 등)이 방식의 장점은 각 단계에서 Storybook으로 컴포넌트를 검증할 수 있다는 것이다. 1단계에서 Button의 모든 상태를 Story로 만들어두면, 2단계에서 SearchBar를 만들 때 Button이 정상적으로 동작하는지 이미 확인된 상태이므로 SearchBar의 로직에만 집중할 수 있다.
프로젝트에 도입하면 좋겠다고 생각한 이유
디자인과 개발 간의 간극을 줄일 수 있다.
Storybook을 배포하면 디자이너가 직접 컴포넌트의 실제 동작을 확인할 수 있다. "이 버튼 호버하면 이렇게 되나요?"를 물어볼 필요 없이 Storybook에서 직접 확인하면 된다.
프로젝트가 끝난 후에도 컴포넌트 문서가 남는다.
포트폴리오에 "이런 컴포넌트들을 만들었고, 각각 이런 상태를 가진다"를 Storybook URL 하나로 보여줄 수 있다면 꽤 강력한 어필이 될 것 같았다.
정리
- Storybook은 UI 컴포넌트를 격리된 환경에서 개발, 테스트, 문서화할 수 있는 프론트엔드 워크숍 도구다.
- 격리된 환경의 핵심 장점은 앱의 비즈니스 로직에 방해받지 않고, 재현하기 어려운 상태도 쉽게 확인할 수 있으며, 개발과 동시에 테스트/문서화가 된다는 것이다.
- Component-Driven Development 방식과 결합하면 바텀업으로 검증된 UI를 쌓아올릴 수 있다.
