Storybook 완전 정복 가이드

울랄라신나·2025년 4월 7일
Reactstorybook

그냥 내가 사용해 본 것들

목록 보기
5/14

참고사이트
https://storybook.js.org/tutorials/intro-to-storybook/react/ko/get-started/
https://velog.io/@phw3071/Stroybook-%EC%8B%9C%EC%9E%91%ED%95%98%EA%B8%B0
https://velog.io/@devstone/%EC%8A%A4%ED%86%A0%EB%A6%AC%EB%B6%81-%EC%A0%9C%EB%8C%80%EB%A1%9C-%ED%99%9C%EC%9A%A9%ED%95%98%EA%B8%B0
https://lasbe.tistory.com/196

Storybook은 단순한 컴포넌트 전시 도구를 넘어, 효율적인 UI 개발 워크플로우를 구축하는 핵심이다. 이 가이드는 Storybook 설치부터 활용 팁, 피그마 연동까지 Storybook을 제대로 사용하는 방법을 알려주겠다.

✨ 이 가이드의 특징 ✨

  • 핵심 요약: 장황한 설명을 줄이고 핵심 내용만 간결하게 전달한다.
  • 단계별 안내: 설치부터 고급 활용까지 단계별로 따라하기 쉽게 설명한다.
  • 실용적인 팁: 실제 개발에 도움이 되는 유용한 팁들을 제공한다.
  • 시각적 강조: 이미지, 표, 강조를 활용하여 가독성을 높였다.

📌 목차

  • Storybook이란?
  • 스토리북 설치하기
  • 폴더 구조
  • 스토리 만들기
  • 스토리 테스트
  • 피그마 스토리북 연동
  • Chromatic으로 배포하기

1. Storybook이란?

Storybook은 UI 컴포넌트 개발을 위한 오픈 소스 도구입니다. 특히 React, Vue, Angular와 같은 프레임워크에서 자주 사용되며, 독립적인 컴포넌트를 개발하고 시각적으로 테스트할 수 있는 환경을 제공한다.

  • 컴포넌트 중심 개발: Storybook을 사용하면 애플리케이션의 개별 UI 컴포넌트를 독립적으로 개발하고 시각적으로 테스트할 수 있다.
  • 스토리(Story): 컴포넌트의 다양한 상태를 "스토리"라는 형태로 기록합니다. 예를 들어, 버튼 컴포넌트를 클릭된 상태, 비활성화된 상태 등 여러 상태로 시연할 수 있다.
  • 디자인 시스템 관리: 컴포넌트를 스토리로 관리함으로써 일관된 UI 디자인 시스템을 구축하고 유지하기 용이하다.

2. Storybook 설치 및 기본 사용법(React JavaScript 기준)

간단하게 React 프로젝트에 Storybook 시작하기!

개발 환경: React JavaScript 프로젝트 기준 (TypeScript 환경도 유사)

  1. 프로젝트 생성

    $ yarn create react-app .  # yarn 사용 시
# 또는
$ npx create-react-app . # npm 사용 시

  2. Storybook 설치 (자동 설정)

    먼저 React 프로젝트에 Storybook을 설치합니다. 아래 명령어를 실행하여 설치한다.

    $ npx sb init  # Storybook CLI 도구 사용 (자동 설정)
# 또는
$ yarn sb init # yarn 사용 시
    • sb init 명령어는 프로젝트 환경을 자동으로 감지하여 Storybook을 최적 설정으로 설치해준다.
    • 설치 과정 중 패키지 설치 여부 질문에 y를 입력하여 진행한다.

  3. Storybook 실행

    src/stories 디렉터리 내에 스토리를 작성합니다. 예를 들어, 버튼 컴포넌트를 위한 스토리를 TagIcon.stories.js로 작성할 수 있다.

    $ yarn storybook # yarn 사용 시
# 또는
$ npm run storybook # npm 사용 시

    • yarn storybook 명령어를 실행하면 자동으로 Storybook 서버가 실행되고 브라우저가 열린다. (기본 주소: http://localhost:6006)

      ✅ 설치 확인: package.json 파일의 devDependencies 항목에 Storybook 관련 패키지 (@storybook/react, @storybook/addon-* 등)가 추가된 것을 확인한다.

    🎉 Storybook 설치 완료! 🎉

    Storybook이 실행되면 기본 스토리가 표시되고

    이제 Storybook을 사용하여 UI 컴포넌트 개발을 시작할 수 있다.

3. 폴더 구조 이해

Storybook 설치 후 프로젝트 폴더 구조는 다음과 같이 변경된다.

your-project/
├── node_modules/
├── public/
├── src/
│   ├── components/       # (예시) 컴포넌트 폴더
│   │   └── TagIcon.js
│   ├── stories/          # Storybook 예제 스토리 폴더 (삭제 가능)
│   │   └── Button.stories.js
│   └── ...
├── .storybook/          # Storybook 설정 폴더
│   ├── main.js         # Storybook 주요 설정 파일 (필수)
│   └── preview.js      # Storybook UI 미리보기 설정 파일 (필수)
├── package.json
├── yarn.lock
└── ...

📌 주요 폴더 및 파일

폴더/파일설명
.storybook/Storybook 설정 폴더 (필수). Storybook 동작 방식, UI 설정, 애드온 등을 관리합니다.
.storybook/main.jsStorybook 주요 설정 파일 (필수). 애드온 설정, 스토리 파일 경로 설정 등 Storybook 핵심 설정이 포함됩니다.
.storybook/preview.jsStorybook UI 미리보기 설정 파일 (필수). Storybook UI 전역 스타일, 테마, 배경색, viewport 설정 등 미리보기 화면 관련 설정을 합니다.
src/stories/Storybook 예제 스토리 폴더 (선택). Storybook 설치 시 자동으로 생성되는 예제 스토리 파일들이 위치합니다. 필요에 따라 삭제하거나 사용자 스토리 폴더로 활용 가능합니다.
*.stories.js스토리 파일 (필수). 컴포넌트 스토리를 작성하는 파일입니다. 파일명 규칙 .stories. (js, jsx, ts, tsx, mdx)만 지키면 폴더 위치는 자유롭습니다.
*.stories.mdx스토리 문서 파일 (선택). MDX (Markdown + JSX) 문법을 사용하여 컴포넌트 문서, 사용법, 데모 등을 작성합니다.

💡 폴더 구조 팁

  • src/stories/ 폴더는 필수가 아니다. 스토리는 프로젝트 내 어떤 폴더에든 위치할 수 있음
  • 컴포넌트 폴더(src/components/)와 스토리 폴더를 분리하여 관리하는 것이 일반적
  • 스토리 파일명 규칙 .stories. 을 꼭 지켜주세요. Storybook이 자동으로 스토리를 인식함

4. 스토리 작성법

스토리는 쉽게 말해 하나의 컴포넌트가 실행 가능한 하나의 케이스를 의미한다. 특정한 props를 넘겼을 때, 그 자체가 하나의 스토리가 되고, 그렇게 다양한 스토리들을 정의하면 우리는 스토리북에서 모든 스토리들을 직관적으로 확인할 수 있다.

들어가기에 앞서, 어떤 기준으로 스토리를 만들지 생각해야 한다. 나는 최소 2페이지에 공통적으로 사용되는 컴포넌트일 경우, 스토리로 만들었다.

✍️ 스토리 작성 기본 구조 (TagIcon.stories.js 예시)

import PropTypes from 'prop-types'
const TagIcon = ({ label, icon }) => {
  return (
    <div className='inline-flex items-center gap-1 rounded-[5px] w-auto h-[24px] bg-[#F6F6F6] px-1'>
      {icon && <img src={icon} alt={label} className='w-[16px] h-[16px]' />}
      <span className='flex font-semibold text-[12px] text-black'>{label}</span>
    </div>
  )
}

TagIcon.propTypes = {
  label: PropTypes.string.isRequired,
  icon: PropTypes.string.isRequired,
}

export default TagIcon

와 

// TagIcon.stories.js

import TagIcon from '../components/TagIcon'; // (예시) 컴포넌트 import
import joboffer from '../assets/icons/common/common_tag_joboffer.svg'; // (예시) 아이콘 import
import history from '../assets/icons/common/common_tag_history.svg'; // (예시) 아이콘 import
// ... 다른 아이콘 import

export default {
  title: 'components/TagIcon', // Storybook 메뉴 경로 (필수)
  component: TagIcon,         // 스토리로 만들 컴포넌트 (필수)
  argTypes: {                  // 컴포넌트 props 설정 (선택)
    label: { control: 'text' },   // label prop: 텍스트 입력 컨트롤
    icon: {                     // icon prop: select 컨트롤, 옵션 지정
      control: 'select',
      options: [joboffer, history, /* ... 다른 아이콘 */],
    },
  },
};

// 템플릿 함수 (재사용 가능한 스토리 템플릿)
const Template = (args) => <TagIcon {...args} />;

// 스토리 정의 (컴포넌트의 각 상태를 스토리로 export)
export const JobofferTag = Template.bind({}); // JobofferTag 스토리 생성
JobofferTag.args = {            // JobofferTag 스토리 props 설정
  label: '구인',
  icon: joboffer,
};

export const CareerTag = Template.bind({});   // CareerTag 스토리 생성
CareerTag.args = {             // CareerTag 스토리 props 설정
  label: '경력',
  icon: history,
};

// ... 다른 스토리 export (JobSearchTag, OtherSiteTag, PopularTag, WorktypeTag 등)

🔑 스토리 작성 핵심 요소

  • export default: 스토리 파일의 메타 정보 설정 (필수)
    • title: Storybook 메뉴에 표시될 경로 (필수, 폴더 구조 반영 권장)
    • component: 스토리로 만들 컴포넌트 (필수)
    • argTypes: 컴포넌트 props 타입 및 UI 컨트롤 설정 (선택, props 조작 편의성 향상)
      • control: props UI 컨트롤 종류 설정 (text, select, boolean, color 등)
      • options: select, radio 컨트롤 옵션 목록 지정
  • Template: 스토리 템플릿 함수 (선택, 스토리 재사용성 향상)
    • 컴포넌트를 렌더링하는 기본 템플릿 함수 정의 (props를 받아서 컴포넌트에 전달)
    • .bind({}) 를 사용하여 각 스토리별로 템플릿 함수 복사본 생성
  • 스토리 export (예: export const JobofferTag = Template.bind({});): 컴포넌트의 각 상태를 스토리로 정의 (필수)
    • 스토리 이름 (예: JobofferTag) = Template.bind({}) 로 스토리 인스턴스 생성
    • 스토리이름.args: 해당 스토리의 props 값 설정 (컴포넌트 상태 정의)

✅ 스토리 작성 팁

  • props 종류별 스토리 작성: 컴포넌트가 가질 수 있는 주요 props 조합을 스토리로 구성
  • 상태별 스토리 작성: 컴포넌트의 다양한 상태 (활성, 비활성, 에러, 로딩 등)를 스토리로 만듬
  • UI 컨트롤 활용: argTypes 를 활용하여 Storybook UI에서 props 값을 직접 변경하며 컴포넌트 변화를 확인
  • 템플릿 재활용: Template 함수를 사용하여 스토리 작성 코드 중복을 줄이고 재사용성을 높임

5. 스토리 테스트 및 활용

1. Storybook UI를 통한 시각적 테스트

  • Storybook 서버 실행 후 브라우저에서 스토리 확인 (http://localhost:6006)
  • 작성한 스토리를 Storybook UI에서 시각적으로 확인하고 UI 깨짐, 레이아웃 문제 등을 검토한다.
  • argTypes 로 설정한 UI 컨트롤을 조작하여 props 변경에 따른 컴포넌트 변화를 실시간으로 확인한다.
  • 다양한 브라우저 및 반응형 디자인 환경에서 스토리를 확인하여 호환성 테스트를 진행한다.

2. 실제 프로젝트에서 스토리 활용 (컴포넌트 재사용)

  • Storybook에서 개발 및 테스트 완료된 컴포넌트를 실제 React 프로젝트에서 import 하여 사용한다.

📌 WorkBoard 컴포넌트 예시 (실제 프로젝트 활용)

// WorkBoard.js (예시 컴포넌트)
import React from 'react';
import PropTypes from 'prop-types';
import TagIcon from './TagIcon'; // TagIcon 컴포넌트 import
import ShareViews from './ShareViews'; // ShareViews 컴포넌트 import
import joboffer from '../../assets/icons/common/common_tag_joboffer.svg'; // 아이콘 import
import history from '../../assets/icons/common/common_tag_history.svg'; // 아이콘 import
// ... 다른 아이콘 import
import viewPink from '../../assets/icons/common/common_view_pink.svg'; // 아이콘 import
import bookmarkGray from '../../assets/icons/common/common_bookmark_gray.svg'; // 아이콘 import
import bookmarkPink from '../../assets/icons/common/common_bookmark_pink.svg'; // 아이콘 import

const WorkBoard = ({ title, name, date, like, onClick }) => {
  const bookmarkIcon = like === true ? bookmarkPink : bookmarkGray; // props에 따른 북마크 아이콘 변경
  return (
    <div className='w-[300px] h-[200px]'>
      <img
        src={bookmarkIcon}
        alt='bookmark'
        onClick={onClick}
        className='w-[23px] h-[23px] relative absolute top-[20px] left-[255px] '
      />
      <div className='flex flex-col h-full  border border-[#D6D6D6] rounded-[10px] px-[25px] pt-[25px] pb-[16px] justify-between'>
        <div className='flex-row'>
          <div className='flex flex-wrap gap-2 mb-2'>
            {/* TagIcon 컴포넌트 재사용 */}
            <TagIcon label='인기 글' icon={popular} />
            <TagIcon label='구인' icon={joboffer} />
            <TagIcon label='경력 1~3년' icon={history} />
            <TagIcon label='구직' icon={jobsearch} />
            <TagIcon label='외부 사이트' icon={othersite} />
            <TagIcon label='정규직' icon={worktype} />
          </div>
          <div onClick={onClick} className='text-[18px] font-bold'>{title}</div>
        </div>
        <div className='flex-row  text-[#8E8E8E] text-[14px]'>
          <div onClick={onClick} className='flex justify-end font-bold '>
            {name}
          </div>
          <hr className='border-[#8E8E8E] my-2' />
          <div className='flex items-end justify-between'>
            {date}
            {/* ShareViews 컴포넌트 재사용 */}
            <ShareViews label='123' textColor='text-[#E36397]' icon={viewPink} />
          </div>
        </div>
      </div>
    </div>
  );
};

WorkBoard.propTypes = {
  title: PropTypes.string.isRequired,
  name: PropTypes.string.isRequired,
  date: PropTypes.string.isRequired,
  like: PropTypes.bool.isRequired,
  onClick: PropTypes.func,
};

export default WorkBoard;

content_copydownloadUse code with caution.Jsx

✅ 스토리 테스트 및 활용 팁

  • UI 변경 사항 검토: 컴포넌트 수정 후 Storybook을 통해 UI 변경 사항을 빠르게 검토합니다.
  • 회귀 테스트 (Regression Testing) 도구 활용: Chromatic과 같은 시각적 회귀 테스트 도구를 연동하여 UI 변경으로 인한 예기치 않은 문제 발생을 방지합니다.
  • 컴포넌트 라이브러리 구축: Storybook을 이용하여 컴포넌트들을 체계적으로 관리하고 문서화하여 재사용 가능한 컴포넌트 라이브러리를 구축합니다.
  • 팀 협업 강화: Storybook을 공유하여 팀원들과 UI 컴포넌트 개발 상황을 공유하고 피드백을 주고받으며 협업 효율성을 높입니다.

6. 피그마 스토리북 연동

Figma와 Storybook 연동은 디자인 시안과 개발 컴포넌트 간의 싱크를 맞추고 디자인-개발 협업 효율성을 극대화하는 효과적인 방법이다.

다음 블로그를 참고하길 바란다. 피그마 스토리북 연동

7. StoryBook Chromatic으로 배포하기

다음 블로그를 참고하길 바란다. Chromatic으로 배포하기

마무리하며...

이 가이드가 Storybook을 시작하고 활용하는 데 도움이 되었기를 바랍니다. Storybook과 Chromatic을 적극적으로 활용하여 더욱 효율적이고 즐거운 UI 개발 경험을 만들어보세요!

profile
울랄라신나
방구석 개발자
이전 포스트

React FormData를 사용여부 코드차이

다음 포스트

피그마 스토리북 연동

0개의 댓글