Storybook

소개

Storybook 이란?

• 공식 홈페이지
• 오픈소스 UI 컴포넌트 개발 도구
• 문서화가 쉬운것이 특징
• 애플리케이션 외부 (독립 개발 환경) 에서 실행됨
• 다양한 부가기능 (addons)을 지원함
• 정적버전을 빌드하여 http 서버에 배포 가능
• React를 시작으로 현재는 React Native, Vue, Angular, Svelte 에서 사용 가능

기본 개념

• 스토리북(Storybook)은 컴포넌트와 그 컴포넌트에 대한 스토리들로 구성되어 있음
• 하나의 컴포넌트는 보통 하나 이상의 스토리를 가짐

설치 & 설정

설치하기

• 설치

// npm 설치
npm install --save -g @storybook/cli

// yarn 설치
yarn add global @storybook/cli

// or
npx storybook init

• 실행

// npm
npm run storybook

// yarn
yarn storybook

// 6006 포트 (default)에 프로젝트 실행

기본 구조 및 설정 파일

.storybook
-- main.js
-- preview.js

stories
-- assets
-- XXX.js | jsx | ts | tsx
-- XXX.stories.js | jsx | ts | tsx

• main.js
  • storybook을 위한 config. 각 설정 값들이 담겨 있음
  • stories 와 addons 세팅 - story 파일들이 프로젝트내에 어디에 위치하고 있는지 명시해주기
  • default code

// react
module.exports = {
  "stories": [
    "../stories/**/*.stories.mdx",
    "../stories/**/*.stories.@(js|jsx|ts|tsx)"
  ],
  "addons": [
    "@storybook/addon-links",
    "@storybook/addon-essentials",
    "@storybook/addon-interactions"
  ],
  "framework": "@storybook/react",
  "core": {
    "builder": "@storybook/builder-webpack5"
  }
}

// vue
module.exports = {
  "stories": [
    "../src/**/*.stories.mdx",
    "../src/**/*.stories.@(js|jsx|ts|tsx)"
  ],
  "addons": [
    "@storybook/addon-links",
    "@storybook/addon-essentials"
  ],
  "framework": "@storybook/vue",
}

• preview.js
  • 해당 프로젝트의 모든 Story에 적용될 포맷을 세팅하는 파일
  • 이 포맷에 해당하는 Story의 프로퍼티로 parameters, decorators등이 있음
  • default code

export const parameters = {
  actions: { argTypesRegex: "^on[A-Z].*" },
  controls: {
    matchers: {
      color: /(background|color)$/i,
      date: /Date$/,
    },
  },
}

Story 작성

• 일반적으로 story파일 ( stories.@(js|jsx|ts|tsx) )은 컴포넌트 파일과 같은 경로에 위치 시킴
• CSF (Component Story Format) 형식으로 작성
  • default export, named export 를 이용

React (with Typescript)

• 스토리북에게 문서화하고 있는 컴포넌트에 대해 알려주기 위해, 아래 사항들을 포함하는 default export를 생성
  • component -- 해당 컴포넌트
  • title -- 스토리북 앱의 사이드바에서 컴포넌트를 참조하는 방법

import React from 'react';
import { ComponentMeta } from '@storybook/react';
import { Button } from './Button';

export default {
  title: 'Example/Button',
  component: Button,
} as ComponentMeta<typeof Button>;

• 스토리를 정의하기 위해서 각각의 테스트 상태에 해당하는 스토리를 생성하는 함수를 export ( named export )
  • 스토리는 주어진 상태안에서 렌더링된 요소(예를 들자면, prop가 포함된 컴포넌트)를 반환하는 함수, 이는 함수형 컴포넌트(Functional Component) 와 같음

import React from 'react';
- import { ComponentMeta } from '@storybook/react';
+ import { ComponentStory, ComponentMeta } from '@storybook/react';
import { ComponentMeta } from '@storybook/react';
import { Button } from './Button';

export default {
  title: 'Example/Button',
  component: Button,
} as ComponentMeta<typeof Button>;

+ export const Primary: ComponentStory<typeof Button> = () => <Button primary>Button</Button>;

import React from 'react';
import { ComponentStory, ComponentMeta } from '@storybook/react';
import { Button } from './Button';

export default {
  title: 'Button',
  component: Button,
} as ComponentMeta<typeof Button>;

export const Primary: ComponentStory<typeof Button> = () => (
  <Button backgroundColor="#ff0" label="Button" />
);

export const Secondary: ComponentStory<typeof Button> = () => (
  <Button backgroundColor="#ff0" label="😄👍😍💯" />
);

export const Tertiary: ComponentStory<typeof Button> = () => (
  <Button backgroundColor="#ff0" label="📚📕📈🤓" />
);

• 보일러 플레이트 코드를 줄이기 위해 Template.bind({}) 를 사용해 코드 최적화

import React from 'react';
import { ComponentStory, ComponentMeta } from '@storybook/react';
import { Button } from './Button';

export default {
  title: 'Button',
  component: Button,
} as ComponentMeta<typeof Button>;

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

export const Primary = Template.bind({});
Primary.args = { backgroundColor: '#ff0', label: 'Button' };

export const Secondary = Template.bind({});
Secondary.args = { ...Primary.args, label: '😄👍😍💯' };

export const Tertiary = Template.bind({});
Tertiary.args = { ...Primary.args, label: '📚📕📈🤓' };

Vue

• 스토리북에게 문서화하고 있는 컴포넌트에 대해 알려주기 위해, 아래 사항들을 포함하는 default export를 생성
  • component -- 해당 컴포넌트
  • title -- 스토리북 앱의 사이드바에서 컴포넌트를 참조하는 방법

  import MyButton from "./Button.vue";
  
  export default {
    title: "Example/Button",
    component: MyButton,
    argTypes: {
      backgroundColor: { control: "color" },
      size: {
        control: { type: "select" },
        options: ["small", "medium", "large"],
      },
    },
      // decorators: [ ... ],
    // parameters: { ... }
  };

• 스토리를 정의하기 위해서 각각의 테스트 상태에 해당하는 스토리를 생성하는 함수를 export ( named export )

import MyButton from "./Button.vue";

export default {
  title: "Example/Button",
  component: MyButton,
  argTypes: {
    backgroundColor: { control: "color" },
    size: {
      control: { type: "select" },
      options: ["small", "medium", "large"],
    },
  },
    // decorators: [ ... ],
  // parameters: { ... }
};

export const Primary = () => ({
  components: { MyButton },
  template: '<MyButton :primary="true" label="Button" />',
});

    import MyButton from "./Button.vue";

    export default {
      title: "Example/Button",
      component: MyButton,
      argTypes: {
        backgroundColor: { control: "color" },
        size: {
          control: { type: "select" },
          options: ["small", "medium", "large"],
        },
      },
        // decorators: [ ... ],
      // parameters: { ... }
    };

    export const Primary = () => ({
      components: { MyButton },
      template: '<MyButton :primary="true" label="Button" />',
    });

    export const Secondary = () => ({
        components: { MyButton },
        template: '<MyButton label="Button" />',
    });

    export const Large = () => ({
        components: { MyButton },
        template: '<MyButton :size="large", label="Button" />',
    });

    export const Small = () => ({
        components: { MyButton },
        template: '<MyButton :size="small", label="Button" />',
    });

• 위 예제의 button.vue

<template>
  <button
    :class="classes"
    :style="style"
    class="storybook-button"
    type="button"
    @click="onClick"
  >
    {{ label }}
  </button>
</template>

<script>
export default {
  name: "MyButton",

  props: {
    label: {
      type: String,
      required: true,
    },
    primary: {
      type: Boolean,
      default: false,
    },
    size: {
      type: String,
      default: "medium",
      validator(value) {
        return ["small", "medium", "large"].indexOf(value) !== -1;
      },
    },
    backgroundColor: {
      type: String,
    },
  },

  computed: {
    classes() {
      return {
        "storybook-button": true,
        "storybook-button--primary": this.primary,
        "storybook-button--secondary": !this.primary,
        [`storybook-button--${this.size}`]: true,
      };
    },
    style() {
      return {
        backgroundColor: this.backgroundColor,
      };
    },
  },

  methods: {
    onClick() {
      this.$emit("onClick");
    },
  },
};
</script>

parameters & decorators

• parameters
  • story의 정적 메타데이터를 정의하는데 사용
  • actions, controls, backgrounds 등등 다양한 addon을 설정할 때에도 사용
  • Story parameters, Component parameters, Global parameters 의 세가지 레벨로 나뉨 Global < Component < Story 의 우선순위를 가지며, 이 순서로 렌더링이 됨
• Story parameters

// Button.stories.js|ts|jsx|tsx
import { Button } from './Button';
import { ComponentMeta } from '@storybook/react';
import { Button } from './Button';

export default {
  title: 'Button',
  component: Button,
} as ComponentMeta<typeof Button>;

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

export const Primary = Template.bind({});
Primary.args = {
  primary: true,
  label: 'Button',
};
Primary.parameters = {
  backgrounds: {
    values: [
      { name: 'red', value: '#f00' },
      { name: 'green', value: '#0f0' },
      { name: 'blue', value: '#00f' },
    ],
  },
};

• Component parameters

// Button.stories.ts|tsx
import React from 'react';
import { ComponentMeta } from '@storybook/react';
import { Button } from './Button';

export default {
  title: 'Button',
  component: Button,
  parameters: {
    backgrounds: {
      values: [
        { name: 'red', value: '#f00' },
        { name: 'green', value: '#0f0' },
        { name: 'blue', value: '#00f' },
      ],
    },
  },
} as ComponentMeta<typeof Button>;

• Global parameters

// .storybook/preview.js

export const parameters = {
  backgrounds: {
    values: [
      { name: 'red', value: '#f00' },
      { name: 'green', value: '#0f0' },
    ],
  },
};

• decorators
  • 컴포넌트를 추가적인 마크업으로 랩핑하여 렌더링 하는 기능
  • parameters 와 마찬가지로 Story decorators, Component decorators, Global decorators 레벨이 존재
• Story decorators

// Button.stories.js|jsx
import React from 'react';
import { ComponentMeta } from '@storybook/react';
import { Button } from './Button';

export default {
  title: 'Button',
  component: Button,
} as ComponentMeta<typeof Button>;

const Template = (args) => <Button {...args} />;

export const Primary = Template.bind({});
Primary.decorators = [
  (Story) => (
    <div style={{ margin: '3em' }}>
      <Story />
    </div>
  ),
];

• Component decorators

// Button.stories.ts|tsx
import React from 'react';
import { ComponentMeta } from '@storybook/react';
import { Button } from './Button';

export default {
  title: 'Button',
  component: Button,
  decorators: [
    (Story) => (
      <div style={{ margin: '3em' }}>
        <Story />
      </div>
    ),
  ],
} as ComponentMeta<typeof Button>;

• Global decorators

// .storybook/preview.js
import React from 'react';

export const decorators = [
  (Story) => (
    <div style={{ margin: '3em' }}>
      <Story />
    </div>
  ),
];

테스트 및 배포

정적 앱으로 배포

• npm run build-storybook / yarn build-storybook 을 실행
• storybook-static 폴더에 Storybook이 생성되며 정적 사이트 호스팅 서비스에 배포 가능

Chromatic을 이용한 배포

• 공식 사이트
• github 원격 저장소에 프로젝트 푸시
• Chromatic 설치

yarn add -D chromatic

• Chormatic 에 로그인 (github 계정)!
• 원격저장소에 올려둔 프로젝트 추가
• 프로젝트 추가후 생성된 프로젝트 토큰을 복사한뒤, 아래 명령어를 실행하여 배포!

npx chromatic --project-token=토큰

추가 사항

Addon

• 스토리북을 위한 추가 기능
• IDE의 마켓플레이스 처럼 다른 개발자가 등록해놓은 추가 기능들을 적용 할 수 있음

참고 사항

• 튜토리얼 예제 (React)