Storybook은 뭘까

목차

1. Storybook이란?

    1.1 스토리북 특징

    1.2 스토리북 구성

2. Storybook 시작하기

3. Storybook 사용하기

---

1. Storybook이란?

스토리북(Storybook)은 UI 컴포넌트를 독립적으로 개발하고 테스트하도록 돕는 도구이다.

비즈니스 로직 및 컨텍스트로부터 분리된 UI 컴포넌트를 만들고 디자인 시스템을 구축할 수 있다.

https://storybook.js.org/

Storybook: Frontend workshop for UI development

 

1.1 스토리북 특징

• 컴포넌트 독립 실행 : 앱과 분리된 환경에서 컴포넌트를 렌더링하고 테스트할 수 있다.
• 상호작용 문서화 : 컴포넌트의 상태, props, UI 동작 등을 시각적으로 문서화할 수 있다
• 디자인 시스템 지원 : 스타일 가이드 구축 및 디자이너와의 협업에 좋다.
• 다양한 프레임워크 지원 : React, Vue, Angular, Svelte, Web Components 등의 다양한 환경을 지원한다.
• 애드온 확장성 : 접근성 검사, viewport 확인, 테스트 통합 등 여러 애드온을 제공한다.

 

1.2 스토리북 구성

스토리북을 설치하면 stories 폴더가 생기고, 샘플 코드 파일들이 생성된다.

Button.tsx, button.css, Buttons.stories.tsx 이런 식으로 세 개가 한 세트이다.

tsx와 css는 우리가 잘 알고 있는 컴포넌트와 스타일 파일이다.

 

스토리북은 ~~stories.tsx 형태의 파일로 해당 컴포넌트를 화면에 표시한다.

이 파일들을 스토리라고 부른다.

---

2. Storybook 시작하기

1. 스토리북 설치

우선 스토리북을 설치하자. sb 말고 storybook으로 써도 된다.

설치하는데 시간이 꽤 걸리니까 좀 딴청 피워도 된다.

대신 중간중간 선택하라는 게 있어서 그런 거 확인해줘야 한다.

npx sb@latest init

 

 

스토리북 설치가 완료되면 아래 명령어로 열린 브라우저에서 스토리북 실행을 확인할 수 있다.

설치할 땐 sb로도 되길래 npm run sb 입력해봤는데 그건 안된단다. 흥

npm run storybook

스토리북 예시 페이지

설치 후 생긴 예제 파일들을 stories 폴더에서 확인할 수 있다. button, header, page의 스토리가 생성되어 있다.

.storybook 폴더에서는 main.ts와 preview.ts를 확인할 수 있다.

 

main.ts

 

// main.ts

import type { StorybookConfig } from "@storybook/nextjs-vite";

const config: StorybookConfig = {
  stories: ["../src/**/*.mdx", "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
  addons: [
    "@storybook/addon-onboarding",
    "@chromatic-com/storybook",
    "@storybook/addon-docs",
    "@storybook/addon-a11y",
    "@storybook/addon-vitest",
    "@storybook/addon-styling-webpack",
  ],
  framework: {
    name: "@storybook/nextjs-vite",
    options: {},
  },
  webpackFinal: async (config) => {
    // 필요 시 Webpack 추가 설정 가능
    return config;
  },
  // 글로벌 파라미터
  docs: {
    // @ts-ignore
    autodocs: true,
  },
  staticDirs: ["..\\public"],
};
export default config;

 

1. StorybookConfig는 왜 불러와야할까

StorybookConfig는 스토리북 설정을 모아놓은 파일로, 어떤 프레임워크, 애드온, 빌드 설정을 할지 지정할 수 있다.

 

2. addons는 뭘까

addons는 스토리북 기능 확장 플러그인 모음이다.

키워드를 보고 설치된 애드온 패키지를 확인할 수 있다.

• @storybook/addon-links : 스토리 간 링크 연결
• @storybook/addon-essetials : 스토리북의 기본 유용 기능 세트(controls, actions, docs 등)
• @storybook/addon-interactions : 상호작용 테스트 지원

3. framework

스토기북이 어떤 UI 프레임워크를 사용할 지 지정한다.

나의 경우, React 프로젝트에서 Webpack5를 사용해 스토리북을 구동하겠다는 의미이다. (storybook은 webpack 기반임)

 

4. webpackFinal이란?

Webpack 빌드 설정을 커스터마이징 하는 함수로, Webpack 설정에 추가 수정이 필요하면 이 함수로 변경할 수 있다.

예를 들어 TailwindCSS 관련 로더 설정 추가, 특정 모듈 처리 방식 변경 등에 쓰인다.

 

5. docs란?

스토리북 문서화 관련 설정으로, autodocs는 스토리북 버전 9이상에서 새로 도입된 자동 문서화 기능 옵션이다.

타입스크립트 오류가 나는 경우 //@ts-ignore를 사용하여 주석 다음 코드 라인의 타입 오류를 무시하도록 할 수 있다.

타입 오류 자체를 없애려면 정확한 타입 정의가 필요하다.

 

6. 글로벌 파라미터 지정이란

스토리북 전역 설정값으로, 모든 스토리에 공통 적용되는 파라미터(뷰포트 크기, 배경색, 행동 로깅 등)을 지정한다.

 

7. 위 설정들이 TailwindCSS 적용을 가능하게 하는 이유

TailwindCSS는 PostCSS를 기반으로 작동하므로, 스토리북 빌드 시 PostCSS와 TailwindCSS를 함께 처리해야한다.

이를 위해 webpackFinal에서 PostCSS 로더 설정을 추가하거나, 설정 파일에 globals.css를 import 해야한다.

 

 

preview.ts

import type { Preview } from "@storybook/nextjs-vite";
import "../src/app/globals.css";

const preview: Preview = {
  parameters: {
    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;

tailwindcss를 storybook에 적용하기 위해서 import "../src/app/globals.css"를 추가해준다.

---

3. Storybook 사용하기

npm run storybook 명령어로 storybook 실행하면 샘플 코드들이 그리는 화면을 볼 수 있다.

 

좌측 메뉴 / 컨트롤 패널

좌측 메뉴에서 샘플로 생성된 컴포넌트들을,

컨트롤 패널에서 Button 컴포넌트의 Props를 확인할 수 있다.

Props의 값은 패널에서 쉽게 변경해보며 props에 따른 모양을 확인할 수 있다.

 

 

 

 

참고

Storybook for React tutorial

Storybook Tutorials