Storybook

Storybook이란?

UI 컴포넌트를 개발할 때 체계적이고 효율적으로 개발할 수 있도록 도와주는 유용할 툴

다양한 상태(스토리)에 따라 변경되는 스타일을 문서 형태로 관리한다.

장점

• 컴포넌트를 개별적으로 관리할 수 있고 다양한 시나리오에서의 동작을 간편하게 확인 가능

• 스토리북을 사용하면 반강제로 재사용성을 고려한 깔끔한 컴포넌트를 작성하게된다.

• 문서형태로 관리되기 때문에 컴포넌트를 더욱 쉽게 이해하고 사용할 수 있게 된다.

• 앱과 별개로 배포할수 있어 작업물을 공유하기 쉽다.

• 디자이너와 소통하기 쉬워진다.

• 높은 품질의 애플리케이션을 개발하는데 도움이 된다.

단점

• 학습곡선이 꽤 높은 편이다.

• 지속적으로 관리가 필요하며, 스토리북 파일이 늘어날수록 관리하기 어려워진다.

• 테스트 작성과 마찬가지로 개발 외 부가적인 시간이 필요해 전체 개발 시간이 증가하게 된다.

Install

npx sb init

Run

스토리북을 실행시켜 별도의 웹에서 문서화된 스토리북을 확인할 수 있다.

default porrt 6006

npm run storybook 

Config

스토리북을 설치가 완료되면 루트 경로에 스토리북 환경설정 파일(main.ts, preivew.ts)이 담긴 .storybook 디렉토리가 추가된다.

main.ts

스토리북의 메인 설정 파일, 스토리북의 환경 설정과 다양한 옵션을 설정할 수 있다.

• stories → 로드할 스토리북 파일을 지정

• addon → 사용할 addon을 등록한다. (등록한 순서에 따라 스토리북 문서에 표시된다.)

• typescript → 타입스크립트와 관련된 옵션

• framework → 스토리북에서 사용할 프레임워크 지정

• core → 스토리북의 세부적으로 제어할 수 있는 옵션

• docs → 스토리북 문서화와 관련된 옵션

• webpackFinal → 스토리북에서 사용할 웹팩 설정을 변경하는 옵션

• staticDirs → 정적 파일이 있는 경로를 지정

import TsconfigPathsPlugin from 'tsconfig-paths-webpack-plugin';
import type { StorybookConfig } from '@storybook/nextjs';

const config: StorybookConfig = {
  stories: [{ directory: '../src', files: '**/*.stories.{ts,tsx}'}],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    '@storybook/addon-controls',
    '@storybook/addon-a11y',
    '@storybook/addon-actions',
    '@storybook/addon-interactions',
  ],
  typescript: {
    check: false, // 타입 체크 X
  },
  framework: {
    name: '@storybook/nextjs',
    options: {},
  },
  core: {
    disableTelemetry: true, // 사용자 데이터를 수집하지 않도록 설정
  },
  docs: {
    autodocs: 'tag', // 태그를 기반으로 자동화 문서 생성
  },
  webpackFinal: async (config: any) => {
    // tsconfig에 설정된 경로 설정을 스토리북에도 적용
    config.resolve.plugins.push(new TsconfigPathsPlugin({}));
    return config;
  },
  staticDirs: ['../public'],
};
export default config;

addon이란 스토리북 기능을 확장하는 모듈로 특정 기능을 추가하거나 기본 기능을 개선하여 보다 유용하게 스토리북을 관리할 수 있게 도움을 준다.

preview.ts

화면에 표시되는 스토리북을 커스터마이징 할 수 있는 설정 파일

• parameters → 컨트롤러, 액션, 인터랙션 등의 스토리의 상호작용들을 전역으로 제어

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

const preview: Preview = {
  parameters: {
    actions: { argTypesRegex: '^on.*' }, // on으로 시작하는 이벤트들의 로그 수집
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/,
      },
    },
  },
};

export default preview;

With Typescript

타입스크립트와 같이 사용하게되면 스토리북의 문서화 작업이 엄청 간편해진다.

스토리북은 타입스크립트와 함께 사용할 경우, 컴포넌트에 정의된 인터페이스를 인식하여 컴포넌트의 정보를 자동으로 입력해주므로 description, default, control과 같은 정보를 입력해 줄 필요가 없어지기에 생산성이 향상된다.

Optional props Issue

스토리북에서 optional props를 읽을 때 undefined 값도 옵션에 포함시켜 표시해주는 이슈가 있었다.

undefined 옵션이 들어가면서 자동으로 설정된 control type도 문제가 생겼다.

원인은 스토리북 설정 파일인 main.ts에서 설정된 reactDocgen에서 사용되는 react-docgen-typescript 설정 문제였다.

react-docgen-typescript는 컴포넌트의 props를 자동으로 문서화하는 기능을 수행하는데, 이때 optional props가 undefined 값을 가질 수 있기 때문에 문서화에 포함시킨다.

typescript: {
  check: false,
  checkOptions: {},
  reactDocgen: 'react-docgen-typescript',
  reactDocgenTypescriptOptions: {
    shouldExtractLiteralValuesFromEnum: true,
    propFilter: (prop) => (prop.parent ? !/node_modules/.test(prop.parent.fileName) : true),
  },
},

관련 옵션을 제거하 스토리북을 재실행을 해보니 undefined 값을 제외한 값들이 올바르게 표시되었다.

typescript: {
  check: false,
},

react-docgen-typescript란?

typescript로 작성된 리액트 컴포넌트의 props 정보를 추출하는 라이브러리로 jsDoc 주석을 활용하는 등의 보다 정교하게 props 정보를 추출해준다.

해당 라이브러리를 쓰지 않아도 스토리북은 내부적으로 타입스크립트를 컴파일해서 props 타입 정보를 추출해준다.