스토리북 컴포넌트 개발

스토리북(Storybook)은 UI 컴포넌트를 독립적으로 개발하고 문서화하는 프론트엔드 도구다. 컴포넌트를 실제 애플리케이션에서 분리해 다양한 상태를 독립적으로 확인하고 테스트할 수 있게 하며, 디자이너-개발자 간 협업 효율을 높인다. 처음 리액트를 기반으로 개발되었고 이후 Vue, Angular, Web Components, Svelte 등 다양한 프레임워크를 지원한다.

스토리북은 컴포넌트를 목록화해 언제든 확인 가능하게 하고, Mockup 상태 값을 넣어 각종 상태에 따라 실시간으로 디자인이 변경되는 것을 볼 수 있다. 개별 컴포넌트뿐 아니라 여러 컴포넌트를 묶은 페이지 단위로도 표시할 수 있어, 기획·디자인 파트와 협업하며 케이스를 사전 테스트하고 빠르게 수정을 반영하는 데 유용하다.

기본 설치와 구조: npx create-react-app으로 리액트 프로젝트 생성 후 npx -p @storybook/cli sb init으로 스토리북을 추가하면 .storybook 폴더가 생성된다. main.js는 스토리북 자체 구성 파일이고, preview.js는 스토리 구성 파일이다. 하나의 컴포넌트를 등록하려면 .js(컴포넌트 로직), .css(스타일), .stories.js(스토리북 노출 설정) 세 파일이 필요하다. 반복되는 컴포넌트는 Template.bind({})로 Template화해 args에 상태값을 주입하는 방식으로 가독성을 높인다.

스토리북의 핵심은 애드온(addon) 시스템이다. 기본 설치 시 @storybook/addon-actions와 @storybook/addon-essentials가 포함된다.

addon-actions는 이벤트 핸들러가 수신한 데이터를 스토리북 패널에서 직접 확인할 수 있게 한다. argTypes에서 단일 이벤트를 설정하거나 actions() 함수로 다중 이벤트를 한번에 등록할 수 있다.

addon-essentials에 포함된 주요 애드온은 두 가지다. Docs는 컴포넌트의 각 상태별 코드를 show/hide code로 즉시 확인하고, 옵션 값들을 테이블로 정리해 협업 시 문서 역할을 한다. Viewport는 INITIAL_VIEWPORTS 설정으로 다양한 디바이스 해상도에서 컴포넌트를 미리 확인할 수 있다.

addon-console은 필수 애드온 외 유용한 확장으로, 개발자 도구를 열지 않고도 스토리북 내부에서 직접 콘솔 로그를 확인할 수 있다. 스토리북은 간혹 이벤트를 외부로 전달하지 못하는 경우가 있어, 내부 콘솔 애드온 활용이 권장된다. addDecorator와 withConsole()을 조합하면 콘솔 메시지에 스토리 경로가 접두사로 붙어 여러 컴포넌트의 이벤트를 구분하기 쉬워진다.

핵심 내용

  • 스토리북: UI 컴포넌트를 앱에서 분리해 독립적으로 개발·문서화하는 도구
  • 설치: npx -p @storybook/cli sb init → .storybook/main.js + preview.js 구성
  • 컴포넌트 1개 = 로직 .js + 스타일 .css + 스토리 .stories.js 세 파일
  • Template화: 반복 컴포넌트를 Template.bind({})로 묶고 args로 상태 주입
  • addon-actions: 이벤트 핸들러 수신 데이터를 패널에서 즉시 확인
  • addon-essentials/Docs: 상태별 코드 + 옵션 테이블 → 협업 문서 역할
  • addon-essentials/Viewport: 디바이스별 해상도 미리보기
  • addon-console: 내부 콘솔로 이벤트 디버깅, 스토리 경로 접두사로 구분 가능
  • 이벤트 외부 미전달 문제 대응: 스토리북 내부 콘솔 애드온 활용 권장

관련 개념

출처

최종 업데이트: 2026-05-01 | 출처 2개