Storybook 설치하기

목차 (OPEN)

• 🟥 Storybook 설치
• 🟧 Storybook 기본 파일들
• 🟨 스토리북에 Material Symbols 아이콘 추가하기

 

 

 

 

(현재 저는 pnpm + React + TypeScript 환경에서 개발 중입니다 👩🏻‍💻)

 

🟥 Storybook 설치

일단 프로젝트 루트에서 아래의 명령어를 실행한다.

pnpm dlx storybook@latest init

 

이렇게 하면 Storybook이 현재 프로젝트의 환경을 자동으로 감지하고,

.storybook 폴더와 기본 스토리 파일들을 생성해준다.

 

잘 설치되었는지 확인하고 싶다면, 아래의 명령어를 실행해주면 된다.

pnpm run storybook

 

이후 브라우저에서 http://localhost:6006 에 접속하면 Storybook UI를 확인할 수 있을 것이다.

 

 

 

---

🟧 Storybook 기본 파일들

📂 .storybook

이거는 스토리북의 환경설정 디렉토리로,

기본적으로 아래의 파일들이 포함되어 있다.

 

1) main.ts

이는 Storybook의 핵심 설정파일로,

어떤 스토리를 불러올지, 어떤 애드온을 사용할지를 정의한다.

Vite alias 같은 커스터마이징도 여기에서 하면 된다 !

 

내 경우 아래와 같이 설정해주었다.

import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    '@chromatic-com/storybook',
    '@storybook/addon-docs',
    '@storybook/addon-onboarding',
    '@storybook/addon-a11y',
    '@storybook/addon-vitest',
  ],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },
};
export default config;

 

• stories
  • ../src/**/*.mdx 👉🏻 src/ 아래에 있는 모든 .mdx 파일을 스토리로 인식
  • ../src/**/*.stories.@(js|jsx|mjs|ts|tsx) 👉🏻 src/ 아래에 있는 *.stories.tsx 같은 파일을 스토리로 인식
  • 즉, 우리가 컴포넌트 옆에 Button.stories.tsx 같은 파일을 두면 스토리북이 자동으로 잡아주게 된다.
• addons
  • @chromatic-com/storybook 👉🏻 Storybook을 배포/시각 테스트 서비스인 Chromatic과 연결해주는 애드온
  • @storybook/addon-docs 👉🏻 각 스토리에 대해 Docs 탭을 만들어주는 애드온
  • @storybook/addon-a11y 👉🏻 웹 접근성 가이드라인에 맞는지 자동으로 체크해주는 애드온
  • @storybook/addon-vitest 👉🏻 Vitest 테스트 결과를 스토리북과 통합할 수 있게 해주는 애드온
• framework
  • 스토리북이 어떤 빌드 툴과 프레임워크를 기반으로 동작할지를 결정해준다.

 

 

2) preview.ts

이거는 스토리북 전체에 공통으로 적용되는 설정으로,

CSS import, 레이아웃 옵션, Docs / Controls 설정 등을 담당한다.

 

내 경우 아래와 같이 설정해주었다.

import type { Preview } from '@storybook/react-vite';

import '../src/styles/index.css';

const preview: Preview = {
  parameters: {
    layout: 'centered',

    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },

    a11y: {
      // 'todo' - show a11y violations in the test UI only
      // 'error' - fail CI on a11y violations
      // 'off' - skip a11y checks entirely
      test: 'todo',
    },
  },
};

export default preview;

• import '../src/styles/index.css'; 👉🏻 전역 스타일을 Storybook에도 적용해준다.
• parameters 👉🏻 스토리북 전체 동작을 제어하는 옵션들의 모음이다.
  • layout
    • centered : 컴포넌트를 캔버스 중앙에 표시
    • fullscreen : 전체 화면을 차지하도록 표시
    • padded : 캔버스 안쪽에 여백을 줘서 표시
  • controls 👉🏻 스토리북 UI에서 props를 조작할 수 있는 Controls 패널을 자동 생성할 때 쓰는 옵션이다.
    • color : props 이름에 background나 color가 들어가면 색상 선택기가 자동으로 붙는다.
    • date : props 이름에 Date가 들어가면 달력 컨트롤러가 자동으로 붙는다.
  • a11y 👉🏻 접근성 애드온의 전역 설정이다.
    • todo : 접근성 위반이 있으면 현재 UI에서만 보여줌
    • error : 위반이 있으면 CI도 실패 처리함
    • off : 접근성 검사를 아예 비활성화함

 

 

3) vitest.setup.ts

스토리북+ Vitest 환경에서 테스트할 때 필요한 설정이다.

import * as a11yAddonAnnotations from '@storybook/addon-a11y/preview';
import { setProjectAnnotations } from '@storybook/react-vite';

import * as projectAnnotations from './preview';

// This is an important step to apply the right configuration when testing your stories.
// More info at: https://storybook.js.org/docs/api/portable-stories/portable-stories-vitest#setprojectannotations
setProjectAnnotations([a11yAddonAnnotations, projectAnnotations]);

 

 

---

🟨 스토리북에 Material Symbols 아이콘 추가하기

나는 이번 서비스 UI에서 구글 머터리얼 아이콘을 자주 쓸 예정이기 때문에

스토리북에서도 동일하게 보일 수 있도록 아래와 같이 설정해주었다.

(.stories 폴더 안에 preview-head.html 파일을 만들어서 추가해주면 된다.)

<link
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200"
  rel="stylesheet"
/>