[React] Storybook으로 컴포넌트 문서화하기

안녕하세요. J4J입니다.

 

이번 포스팅은 Storybook으로 컴포넌트 문서화하는 방법에 대해 적어보는 시간을 가져보려고 합니다.

 

 

 

Storybook이란?

 

Storybook은 제목에서 보이듯이 개발할 때 사용되는 여러 컴포넌트들을 문서화할 수 있는 오픈 소스 도구입니다.

 

여러 협업되는 과정에서 사용될 수 있는 공통 컴포넌트들부터 시작하여 페이지들도 독립적으로 구축할 수 있기 때문에 개발자들이 개발된 컴포넌트 코드들을 사용하고자 할 때 Storybook을 참고하여 더 편리하게 사용할 수 있게 도와줍니다.

 

또한 일반 문서들처럼 단순히 Storybook에 등록할 때 설정한 값에 맞게만 보이는 것이 아니고 radio, text 등을 이용해 각 컴포넌트에서 전달받을 수 있는 props도 실시간으로 변경도 할 수 있습니다.

 

즉, style이 입혀진 재사용 컴포넌트들을 여러 방면에서 활용할 때 많은 도움을 주기에 협업을 할 때 필수적으로 사용되야하는 도구라고 생각합니다.

 

 

 

Storybook 설정 방법

 

[ 1. 패키지 설치 ]

 

$ npx -p @storybook/cli sb init

 

 

 

storybook에서 제공하는 cli를 위와 같이 입력하여 설치해주시면 됩니다.

 

많은 양의 모듈들이 설치되기 때문에 어느 정도 시간이 걸리는 점 참고 부탁드립니다.

 

그리고 설치가 모두 완료되었다면 package.json에 storybook을 위한 scripts가 다음과 같이 생성됩니다.

 

  "scripts": {
    "storybook": "start-storybook -p 6006",
    "build-storybook": "build-storybook"
  },

 

 

 

storybook은 작성한 storybook을 확인할 수 있도록 실행하는 명령어입니다.

 

build-storybook은 작성된 storybook 코드들을 build 하기 위한 용도입니다.

 

추가적으로 storybook과 관련된 소스코드는 .stories.tsx와 같은 형태로 stories가 확장자에 있어야 위의 scripts들의 타겟이 됩니다.

 

 

 

[ 2. 스토리북 실행 ]

 

설치를 하고 src폴더를 확인해보면 다음과 같이 기본적으로 제공해주는 storybook 코드를 확인할 수 있습니다.

 

storybook 소스

 

 

 

해당 코드가 어떻게 동작되는지 확인하기 위해 다음 명령어를 이용해 실행해보겠습니다.

 

$ npm run storybook

 

 

 

그러면 다음과 같은 화면들을 확인할 수 있습니다.

 

실행 화면

 

 

 

실행된 화면에서 Controls 부분을 확인할 수 있습니다.

 

위에서 언급한바와 같이 한번 설정한 props는 고정되는게 아니고 storybook을 통해 실시간으로 변경할 수 있습니다.

 

그러므로 다음과 같이 값을 변경하면 변경된 사항에 맞는 디자인을 확인할 수 있습니다.

 

Controls 수정

 

 

반응형

 

 

[ 3. 스토리북 빌드 ]

 

빌드는 다음 명령어를 입력해주면 됩니다.

 

$ npm run build-storybook

 

 

실행이 모두 완료되면 다음과 같이 storybook-static 폴더가 생기며 빌드된 storybook 파일들이 들어있는 것을 확인할 수 있습니다.

 

build

 

 

 

Storybook 추가하기

 

기본적으로 제공하는 코드말고 새로운 코드를 추가 작성해서 storybook에 넣어보도록 하겠습니다.

 

여러 코드에서 많이 사용되는 text를 추가해볼거고 styled components를 곁들여 보겠습니다.

 

 

 

[ 1. text.ts 파일 생성 ]

 

styled components만 활용하여 스타일이 정의되는 text를 작성해보겠습니다.

 

/src/atoms 경로에 tex.ts 파일을 만들어 다음과 같이 작성했습니다.

 

import styled, { css } from 'styled-components';

// Text에서 사용될 props 정의
export const TextProps = {
    size: ['small', 'medium'] as const,
    color: ['primary', 'error'] as const,
}

// Text에서 사용될 props interface 정의
export interface Iprops {
    size: typeof TextProps.size[number], // 'small' | 'medium'
    color: typeof TextProps.color[number], // 'primary' | 'error'
    weight: number | string,
}

const Text = styled.span<Iprops>`
    letter-spacing: -0.56px;

    ${props => {
        switch(props.size) {
            case 'small':
                return css`
                    font-size: 14px;
                `;

            case 'medium':
                return css`
                    font-size: 18px;
                `;
        }
    }}

    ${props => {
        switch(props.color) {
            case 'primary':
                return css`
                    color: #1ea7fd;
                `;

            case 'error':
                return css`
                    color: #ce1e15;
                `
        }
    }}

    ${props => css`
        font-weight: ${props.weight};
    `}
`

export default Text;

 

 

 

[ 2. text.stories.tsx 파일 생성 ]

 

위에서 작성한 text를 storybook에 추가하기 위해 /src/stories 경로에 text.stories.tsx 파일을 생성해보겠습니다.

 

import * as React from 'react';
import { ComponentStory, ComponentMeta } from '@storybook/react';
import Text, { TextProps } from '../atoms/text';

export default {
  title: 'Atoms/Text', // storybook에 보이는 title
  component: Text, // 사용될 component
  argTypes: { // props로 사용될 타입 정의 (Controls에서 사용 가능)
        size: { 
            options: TextProps.size,
            control: 'radio' 
        },
        color: { 
            options: TextProps.color,
            control: 'radio' 
        },
        weight: {
            control: 'text'
        }
  },
} as ComponentMeta<typeof Text>;

const Template: ComponentStory<typeof Text> = (args) => <Text {...args}>Default Text</Text>;

// 가장 기본적인 컴포넌트
export const Default = Template.bind({});

// 사이즈 변경이 된 컴포넌트
export const Size = Template.bind({});
Size.args = {
    size: 'small'
};

// 색상이 설정된 컴포넌트
export const Color = Template.bind({});
Color.args = {
    color: 'error'
};

// 두께가 설정된 컴포넌트
export const Weight = Template.bind({});
Weight.args = {
    weight: 700
};

 

 

728x90

 

 

[ 3. 실행 결과 ]

 

실행해보면 이전에 기본적으로 있었던 stories 파일과 함께 추가한 코드도 보이는 것을 확인할 수 있습니다.

 

Default

 

Size

 

Color

 

Weight

 

 

 

또한 위에서 했던것처럼 Controls에 있는 props들을 선택하면 선택된 값에 맞는 스타일도 동일하게 실시간으로 확인 가능합니다.

 

Controls 수정

 

 

 

 

 

 

 

이상으로 Storybook으로 컴포넌트 문서화하는 방법에 대해 간단하게 알아보는 시간이었습니다.

 

읽어주셔서 감사합니다.