Storybook 으로 컴포넌트 문서화 — 설치·Knobs·Actions·Docs 한 번에

이 글은 2020년 7월 작성한 Storybook 학습 시리즈 4편을 통합한 아카이브본입니다. 현재 (v8+) 에서는 Controls 가 Knobs 를 대체했고, Docs 는 기본 내장되었습니다.

Storybook 이란?

Storybook 은 React·Vue·Angular 등 다양한 UI 프레임워크를 지원하는 컴포넌트 단위의 개발·문서화 환경 입니다. 애플리케이션 전체를 띄우지 않고 개별 컴포넌트를 격리된 환경에서 다양한 상태로 렌더링해볼 수 있습니다.

디자이너·개발자·기획자가 같은 컴포넌트를 다양한 시나리오로 공유하는 용도로 자주 쓰입니다.

1. 설치와 첫 스토리

npx -p @storybook/cli sb init

stories/ 디렉토리가 자동 생성되며 예제 컴포넌트의 스토리 파일이 함께 들어옵니다. 실행:

npm run storybook

기본 포트 localhost:6006 에서 Storybook UI 가 열립니다.

스토리 작성 기본

import React from 'react';
import Button from './Button';

export default {
  title: 'Components/Button',
  component: Button,
};

export const Primary = () => <Button label="Primary" />;
export const Secondary = () => <Button label="Secondary" />;

• title — Storybook UI 좌측 트리의 그룹/이름
• 각 export 는 독립된 스토리로 등록
• 하나의 스토리 파일에 여러 variant 를 나열

2. Knobs 애드온 — 런타임 props 조작

Knobs 는 Storybook UI 에서 props 값을 동적으로 변경할 수 있게 해주는 애드온입니다. 디자이너·기획자가 개발자 도움 없이 "버튼 텍스트를 바꿔보고 싶다", "색상을 바꿔보고 싶다" 를 즉시 시도할 수 있습니다.

설치

npm install --save-dev @storybook/addon-knobs

.storybook/main.js 에 등록:

module.exports = {
  addons: ['@storybook/addon-knobs'],
};

사용

import { text, boolean, number } from '@storybook/addon-knobs';

export const Configurable = () => (
  <Button label={text('Label', 'Click me')} disabled={boolean('Disabled', false)} size={number('Size', 16)} />
);

Storybook UI 하단에 입력 필드가 자동 생성되어 실시간으로 props 가 반영됩니다.

3. Actions 애드온 — 이벤트 로깅

버튼 클릭 같은 이벤트 핸들러가 실제로 호출되는지 확인하는 용도입니다.

import { action } from '@storybook/addon-actions';

export const Clickable = () => <Button onClick={action('button-clicked')} label="Click" />;

버튼을 클릭하면 Storybook UI 의 Actions 패널에 button-clicked 이벤트가 로그로 남고, 전달된 인자까지 확인할 수 있습니다.

4. Docs 애드온 — 자동 문서 생성

컴포넌트의 props 타입·설명·사용 예시를 자동 추출 하여 문서 페이지를 만들어줍니다.

설치

npm install --save-dev @storybook/addon-docs

TypeScript 를 쓰면 props 타입이 자동 인식되어 문서 테이블로 렌더됩니다. JSDoc 주석을 달면 각 prop 의 설명까지 포함됩니다.

생성 결과

• Canvas 탭: 각 스토리의 시각적 렌더링
• Docs 탭: props 표, 코드 스니펫, 설명 문서 자동 구성

디자이너·PM 과 설계 합의점으로 쓰기에 적합합니다.

학습 회고

Storybook 도입의 가장 큰 이득은 컴포넌트 개발의 맥락을 분리 할 수 있다는 점이었습니다. 특정 상태를 재현하기 위해 애플리케이션 전체를 돌리지 않아도 되고, 엣지 케이스(빈 상태·에러·로딩)를 한 번에 모아볼 수 있었습니다.

디자인 QA 와 협업할 때도 효과가 컸습니다. "이 변형을 봐줘" 라고 링크 하나만 보내면 되기 때문에 말로 설명하는 것보다 의사소통 비용이 낮아졌습니다.

현재 Storybook v8 이상에서는 Knobs 대신 Controls, Docs 는 기본 내장되는 등 API 가 많이 정리되었습니다. 하지만 "컴포넌트를 격리해서 모든 variant 를 눈으로 확인한다" 는 핵심 가치는 그대로입니다.