스토리북 사용해보기

한호수 (The Lake)·2023년 7월 28일

개요

전에 만든 사이드 프로젝트에 스토리북 공부겸 셋업부터 각 컴포넌트별 스토리북 코드를 생성하고 배포부터 깃허브 액션으로 CI/CD까지 적용하였다. 스토리북 공식문서가 잘나와있어서 쉽게 적용할 수 있었다.

스토리북 설치 및 실행하기

npx storybook@latest init

위 명령어를 CLI에 입력하면 예시 코드부터 스토리북에 필요한 의존성 라이브러리들을 모두 package.json에 추가하여준다.
(ESLint도 추가하여준다. 기존에 설정파일이 있다면 설정만 추가된다.)

설치 후 package.json에 보면 스크립트가 추가되었을텐데 수정하지 않았다면 npm run storybook으로 스토리북 실행이 가능하다.

npm run storybook

포트를 수정하지 않았다면 실행 후 http://localhost:6006/ 로 접근할 수 있으며 메인 화면은 아래와 같다.

왼쪽 example에 Button 컴포넌트를 클릭해서 보면 Button 컴포넌트에 대한 문서가 나오며 어떤 옵션(props)를 받는 컴포넌트인지 나온다.

스토리북이 좋은점은 단순 문서에서 그치지 않고 직접 옵션들을 조작하면서 어떻게 바뀌는지 눈으로 볼수있다는 점인것 같다.

스토리파일 작성하기

처음 스토리북을 사용할때 추가된 파일 중 Button.stories.js를 보면 아래와 같다.

간략하게 보기 위해 주석은 제거하였습니다.
typescript를 사용하기 때문에 js만 사용하는 환경과는 다를 수 있습니다.

// Button.stories.ts
import type { Meta, StoryObj } from '@storybook/react';

import { Button } from './Button';

const meta = {
  title: 'Example/Button',
  component: Button,
  parameters: {
    layout: 'centered',
  },
  tags: ['autodocs'],
  argTypes: {
    backgroundColor: { control: 'color' },
  },
} satisfies Meta<typeof Button>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Primary: Story = {
  args: {
    primary: true,
    label: 'Button',
  },
};

// (...)

스토리를 작성할때 meta 변수를 만들고 해당 스토리에 대한 config를 넣어준다.

meta.title

경로를 포함한 스토리의 이름, 중복되면 안되며, 생략할 경우 자동으로 생성된다.

meta.component

스토리에 사용될 컴포넌트를 넣어준다.

meta.parameters

일반적으로 Storybook 기능 및 애드온의 동작을 제어하는데 사용되는 속성
ex) 컴포넌트를 보여주는 스토리의 배경을 바꾸고싶다.

const meta = {
  component: Button,
  parameters: {
    backgrounds: {
      default: 'gray', // 기본값을 gray로 사용한다.
      values: [
        { name: 'gray', value: '#f0f0f0' },
        { name: 'white', value: '#ffffff' },
      ],
    },
    layout: 'centered', // 컴포넌트를 가운데 정렬 시킨다.
  },
  //(...)
} satisfies Meta<typeof Button>;

아래와 같이 기본값이 gray로 변경되며 왼쪽 위 background 버튼을 눌러 선택할 수 있다.

meta.tags

자동 문서화를 설정할때 주로 사용된다.['autodocs']를 사용하면 별도의 mdx 문서가 없더라도 자동으로 스토리 밑에 Docs를 생성해준다.

meta.argTypes

스토리의 현재 props 값을 보여주고 사용자가 이를 변경할 수 있도록 지원하는 여러 Input들을 제공한다.
ex) backgroundColor 를 text로 받고싶다.

argTypes: {
    backgroundColor: { control: 'text' },
  },

유저의 입력을 받는 Input이 텍스트를 입력받는 폼으로 변경되었다.

Description 작성

컴포넌트를 스토리화하고 끝이아니라 각 속성별로 어떤 기능을 하는지 설명을 적어주어야 한다. 컴포넌트에 직접 작성할 수도 있고 스토리 파일의 meta에 작성할 수도 있다.

meta에 작성

컴포넌트 설명은 meta.parameters.docs.description.component에 작성하고 각 속성에 대한 설명은 meta.argTypes.props.description에 작성한다.

const meta = {
  // (...)
  parameters: {
    docs: {
      description: {
        component: '버튼 컴포넌트 입니다.',
      },
    },
  },
  argTypes: {
      backgroundColor: {
        control: 'text',
        description: 'meta에 작성한 description',
      },
    },
  // (...)
} satisfies Meta<typeof Button>

JSDocs로 작성

타입스크립트의 interface 내부에 JSDocs 문법으로 주석을 달면 스토리북의 Description에 나온다.

Description은 우선순위가 있어서 meta에 작성한 docs가 우선순위가 높습니다. ( 링크 )

// Button.tsx
interface ButtonProps {
  /**
   * 인터페이스의 타입위에 JSDocs 주석을 달면 스토리북에 적용된다.
   */
  primary?: boolean;
  /**
   * 여기도 마찬가지
   */
  backgroundColor?: string;
  // (...)
}

/**
 * 컴포넌트에 관한 설명을 작성할 수 있다.
 */
export const Button = ({
  primary = false,
  size = 'medium',
  backgroundColor,
  label,
  ...props
}: ButtonProps) => {
 // (...)
};

스토리북 배포하기

스토리북은 정적페이지로서 배포해두면 팀원들과 협업할때 쉽게 참고할 수 있게된다.
스토리북에서는 스토리북 관리자가 만든 무료 배포 서비스인 Chromatic을 사용을 권장한다.

일단 프로젝트에 chromatic 패키지를 설치한다.

npm i -D chromatic

크로마틱 로그인 버튼을 눌러 Github로 로그인하고 권한을 승인한다.
새로운 프로젝트를 생성하여 Github에 storybook을 배포할 레포를 선택한다.
아래 사진와 같이 나오면 본인의 project-token를 넣고 명령어를 터미널에서 실행한다.

npx chromatic --project-token=<project-token>

위 과정이 끝나면 배포를 시작하며 배포가 완료되면 배포된 링크를 제공한다.
링크로 들어가면 배포된 스토리북을 확인할 수 있다. 하지만 코드가 깃허브에 push 될 때마다 이걸 반복한다면 많은 시간을 낭비하게 될것이다. Github Actions를 통해 push가 될때마다 storybook이 build되도록 해보자.
GitHub에 repo를 선택하고 Actions로 들어가 새로운 workflow를 만들어준다.
스토리북에서 제공한 workflow를 참고해서 작성한다.


# Workflow name
name: 'Chromatic Deployment'

# Event for the workflow
on: push

# List of jobs
jobs:
  test:
    # Operating System
    runs-on: ubuntu-latest
    # Job steps
    steps:
      - uses: actions/checkout@v1
      - run: yarn
        #👇 Adds Chromatic as a step in the workflow
      - uses: chromaui/action@v1
        # Options required for Chromatic's GitHub Action
        with:
          #👇 Chromatic projectToken, see https://storybook.js.org/tutorials/intro-to-storybook/react/ko/deploy/ to obtain it
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          token: ${{ secrets.TOKEN }}