[Storybook] Storybook 설명

출처: https://unsplash.com/ko/%EC%82%AC%EC%A7%84/g6Wd6MS8lms

 

프로젝트 설치

yarn install

 

프로젝트 실행

yarn storybook

 

스토리북 공식문서

Install Storybook

 

---

 

1. Story?

• 스토리북에서 말하는 스토리는 UI 컴포넌트가 특정 상태로 렌더링 된 형태를 말합니다. 따라서 UI 컴포넌트는 여러 형태의 스토리를 가질 수 있습니다.
• 모든 스토리 파일은 *.stories.mdx, *.stories.tsx 등과 같은 이름으로 설정합니다.

 

2. Story 작성하기

기본적으로 스토리는 두 가지 형태로 작성할 수 있습니다. Docs Page와 MDX 입니다.

 

Docs Page는 CSF을 사용하여 스토리북에서 기본적으로 제공하는 문서 형식입니다.(the zero-config default documentation, out of the box) MDX는 기본으로 제공되는 Docs Page를 커스텀(If you want more control, 좀 더 많은 컨트롤을 원할 경우)할 수 있고 long-form 형태의 마크다운 문서도 포함 시킬 수 있습니다.

 

1) Docs Page

• CSF(Component Story Format)는 스토리를 작성하는데 사용되는 권장 포멧으로 스토리와 컴포넌트에 대한 메타 데이터를 ES Module의 형태로 정의합니다. 아래의 예시 코드과 같이 작성하는 포멧을 가리킵니다.2

https://storybook.js.org/docs/react/api/csf

Component Story Format (CSF)

• 개별 스토리 파일은 필수적으로 default export(내보내기) 해야 하며, 하나 또는 다수의 named exports를 할 수 있습니다.
• default export를 통해 내보내기한 객체에는 메타데이터를 정의합니다. 메타데이터 객체는 component, title, decorators, parameters 등의 값으로 구성됩니다.
• title - 스토리북 실행 시 왼쪽 사이드바에 나타나는 계층 구조를 나타냅니다. 선택 값이며 고유해야 합니다.
• component - 필수 값입니다. 해당 스토리 파일에서 사용할 컴포넌트를 말합니다.
• decorators - 스토리를 렌더링 할 때, 추가적으로 적용해야할 필요가 있을 때 사용합니다. 주로 여백을 추가하는 것과 같이 markup을 위해 사용하거나 styled-components 와 같은 특정 프레임워크 라이브러리의 추가적인 기능을 적용하기 위해 사용합니다.(예를들어, styled-components ThemeProvider 적용하는 경우) 하단의 preview.js에서 좀 더 자세히 설명하겠습니다. 적용되는 범위에 따라 3개의 계층으로 나뉩니다.(story decorators, component decorators, global decorators)
• parameters - 스토리에 대한 정적 메타데이터 집합입니다. 구체적으로 툴바의 background color,  viewport 등을 설정할 수 있습니다. decorator와 마찬가지로 적용되는 범위에 따라 3개의 계층으로 나뉩니다.(story parameters, component parameters, global parameters)
• named export 형태는 새로운 변수를 통해 스토리를 생성하는 방식을 말합니다. 

//MyComponent.stories.tsx
 
import React from 'react';
import { ComponentStory, ComponentMeta } from '@storybook/react';
import { MyComponent } from './MyComponent';
 
//export default 방식
export default {
  /* 👇 title 프로퍼티는 선택값입니다.
  * 자동으로 title 생성하기
  * https://storybook.js.org/docs/react/configure/overview#configure-story-loading
  */
  title: 'Path/To/MyComponent',
  component: MyComponent,
} as ComponentMeta;
 
 
//named export 방식
export const Basic: ComponentStory = () => ;
 
export const WithProp: ComponentStory = () => ;

 

2) MDX

• MDX는 JSX 와 Markdown을 결합한 표준 파일 형식입니다. MDX 형식의 문서를 작성하기 위해서는 addon-docs(Docs 애드온)이 필요합니다.
• MDX 형태로 작성하게 되면 Markdown으로 작성한 문서와 스토리를 하나의 페이지에서 작성할 수 있습니다. Markdown으로만(only markdown) 이루어진 문서를 작성할 수도 있고 스토리를 함께 작성할 수 있습니다. 해당 프로젝트에서 스토리 외에도 Markdown 을 함께 작성하기 위해 *.stories.mdx 형식을 사용하였습니다.

//Checkbox.stories.mdx
 
import { Canvas, Meta, Story } from '@storybook/addon-docs';
import { Checkbox } from './Checkbox';
 
<Meta title="MDX/Checkbox" component={Checkbox} />
 
export const Template = (args) => <Checkbox {...args} />;
 
# Checkbox
 
`MDX`를 사용하면, 다음과 같이 Checkbox에 대한 스토리를 마크다운 문서와 함께 작성할 수 있습니다.
 
<Canvas>
  <Story 
    name="Unchecked"
    args={{ 
      label: 'Unchecked',
    }}>
    {Template.bind({})}
   </Story>
 
  <Story 
    name="Checked"
    args={{ 
      label: 'Unchecked', 
      checked: true,
    }}>
    {Template.bind({})}
   </Story>
  
  <Story 
    name="Secondary"
    args={{
      label: 'Secondary', 
      checked: true, 
      appearance: 'secondary',
    }}>
    {Template.bind({})}
   </Story>
</Canvas>

https://storybook.js.org/docs/react/writing-docs/mdx

MDX

 

addon-docs에 대해서
Docs 애드온은 @storybook/addon-docs에 내장되어 있는 라이브러리(?)로 Meta, Canvas, Story, ArgsTable 등의 블록을 포함합니다. 

<Meta />
CFS 형태로 스토리를 작성할 때 필요한 값들을 설정 할 수 있습니다.(title, component, prameters, decorators, argsType 등)


<Canvas />
소스코드를 제공하는 스니펫을 제공합니다. 이외에도 withToolbar, withSource 등의 옵션도 설정할 수 있습니다.
참고

<Story />
기본적으로 스토리가 렌더링 되는 빌딩 블록입니다. 스토리를 렌더링하는 것 뿐 아니라 정의하는 방식을 제공합니다.
참고


<ArgsTable />
해당 스토리에 대한 arguments(React props) 설정을 표의 형태로 나타냅니다. 특정 arguments가 적용된 컴포넌트의 모습을 즉각적으로 렌더링해주기 때문에 arguments 바꾸어 가며 바로 확인할 수 있습니다. ArgsTable 블록의 story 프로퍼티와 Story 블록에서 name 프로퍼티를 동일하게 설정하는 것으로 사용할 수 있습니다.  ArgsTable은 argTypes에 기반해서 생성되는데 argTypes은 Meta 블록에서 설정 가능합니다. 
참고   


argTypes
참고

 

Template.bind({})에 대해서

• 하나의 스토리에서 템플릿을 활용하여 프로퍼티에 따라 달라지는 다양한 스토리를 만들 수 있습니다.
• Template을 설정하고 JavaScript의 bind 메서드를 사용합니다. (bind 메서드는 함수를 복사하는 용도로 사용 - 참고)
• Template을 사용하여 공통 프로퍼티는 적용하고 개별 프로퍼티를 설정할 수 있습니다.

How to write stories

 

3. 화면 설명

https://storybook.js.org/docs/react/get-started/browse-stories

Browse Stories

 

4. 폴더 설명

1) .storybook 폴더

• .storybook 폴더를 통해 설정할 수 있습니다.

https://storybook.js.org/docs/react/configure/overview

Configure Storybook

 

2) main.js

• 메인 설정 파일입니다.
• 스토리북 서버의 동작에 대한 설정입니다. 설정을 변경한다면 스토리북을 재시작 해야 합니다.
• stories, addons, webpackFinal, babel, framework 필드가 있습니다.
• stories
  • 작성한 스토리 파일의 상대적 위치(main.js 기준으로)를 나타내는 배열 형태의 globs 입니다.
• addons
  • 현재 사용 중인 addon 리스트 입니다.
  • essential addons

https://storybook.js.org/docs/react/essentials/introduction

Essential addons

• babel
  • babel 설정
• framework
  • 로딩과 빌드 과정을 돕기 위해 사용되는 특정 framework에 대한 설정 입니다.

https://storybook.js.org/docs/react/configure/overview#configure-your-storybook-project

Configure Storybook

 

3) preview.js

• 스토리가 렌더링 되는 방식과 전역 decorators, parameters를 추가하는데 사용됩니다.
• Canvas 탭에서 해당 컴포넌트가 미리보기 형태로 렌더링 됩니다.
• 다음과 같은 키 값을 갖습니다. globalTypes

https://storybook.js.org/docs/react/configure/overview#configure-story-rendering

Configure Storybook