[React + Typescript + Vite] Storybook 도입기

사이드 프로젝트에서 평소에 관심있었던 스토리 북을 도입해보려고 한다!

Storybook

Storybook은 UI 컴포넌트를 별도로 빌드하고 문서화하는 데 사용되는 오픈 소스 개발 도구이다. Storybook을 사용하면 개발자는 구성 요소의 다양한 상태 또는 변형을 나타내는 각 구성 요소에 대한 개별 스토리를 만들 수 있고, 이러한 스토리는 구성 요소의 동작, 모양 및 사용에 대한 시각적 문서 역할을 하게 된다.

다양한 장점이 있지만 개발자와 디자이너가 컴포넌트를 함께 검토하고 피드백을 제공할 수 있게 하는 협업 툴로서의 장점이 제일 큰 것 같다.
자세한 내용은 공식문서에서 확인하자.

설치

공식문서에 설정 방법이 잘 나와있다.

$ npx storybook@latest init

(yarn 대신 npx로 하면 로컬에 저장하지 않고도 최신 버전의 모듈을 불러와 임시로 실행시키고 파일은 없어짐! 일회성이고, npm 5.2 버전부터는 npx가 기본 패키지로 제공됨)

해당 명령어를 실행하면, cli에서 2가지를 물어본다.
정말 init 할거냐.. Y..예...
추가로 eslint를 사용하는 경우, eslint 플러그인도 추천해준다. Y.. 예.. 설치함다.

eslint plugin 깃헙에 나와 있는 추가 설정들은 자동으로 입력된다!

근데 이런 에러가 남

2:1 error '@storybook/testing-library' should be listed in the project's dependencies, not devDependencies import/no-extraneous-dependencies

해결: eslint 설정 파일의 rule 부분에 다음과 같은 옵션을 추가해주었다.

"import/no-extraneous-dependencies": [
      "error",
      {
        "devDependencies": [
          "**/stories/**",
        ],
        "optionalDependencies": false
      }
    ]

스토리북 관련 파일 (stories 폴더 안의 모든 파일) 의 경우 devDependencies관련 에러를 안 뱉게 하는것임!

폴더 구조

보통 react 프로젝트에서 스토리북 기본 설정을 하면 폴더구조가 다음과 같다.

my-react-app/
  |- src/
      |- components/
      |   |- Button/
      |   |   |- Button.tsx
      |   |- ...
      |
      |- stories/
      |   |- Welcome.stories.ts
      |   |- Button.stories.ts
      |   |- Button.css
      |   |- Button.tsx
      |- main.tsx
      |- App.tsx
      |- ...
  |- .storybook/
      |- main.ts
      |- preview.ts

스토리북을 처음 도입해보는거라, 다음과 같은 의문이 들었다.

stories에 꼭 component tsx 파일이 포함되어야 하는건가? stories 폴더 안에 Button 관련 파일을 모두 묶는 폴더를 생성해도 되는건가?

이에 대한 답은

1. stories에 꼭 컴포넌트 tsx 파일을 위치시킬 필요는 없다. [component].tsx 파일을 어디서든 import 하면 된다.

2. 폴더 구조에 답은 없다. stories 파일을 따로 모아보고 싶으면 stories 파일에 각 컴포넌트별 stories 파일을 생성해도 되고, 컴포넌트 안에서 컴포넌트 별 폴더를 생성한 후 안에 stories 파일을 만들어도 된다.

나는 stories 파일들을 명확하게 분리하고 싶었기에 아래와 같은 폴더구조를 선택했다.

my-react-app/
  |- src/
      |- components/
      |   |- Button.tsx
      |   |- ...
      |
      |- stories/
      |   |- Button.stories.ts
      |   |- ...
      |
      |- main.tsx
      |- App.tsx
      |- ...
  |- .storybook/
      |- main.ts
      |- preview.ts

절대 경로 도입

근데 이렇게 하면 Button 이라는 Component를 가져올 때 마다 ../components/Button 이런 지저분한 경로가 생기므로, 이를 절대 경로로 바꾸어주었다.

tsconfig 파일에서 다음과 같이 component 경로를 설정해주면 된다.

  "compilerOptions": {
    ...
    "baseUrl": "./src",
    "paths": {
      "@styles/*": ["styles/*"],
      "@components/*": ["components/*"]
    }
  },

수정 전 import 구문

import { Button } from '../components/Button';

수정 후 import 구문

import { Button } from '@components/Button';

근데 이렇게 tsconfig만 수정해주면 VSCode에서 다음과 같은 워닝이 뜬다.

Unable to resolve path to module '@components/Button'.eslintimport/no-unresolved

만약 이렇다면, eslint-import-resolver-typescript가 안깔려 있는 상황이면 아래와 같은 명령어로 먼저 설치해주고,

yarn add -D eslint-import-resolver-typescript

이후 esilntrc 파일에 다음과 같이 alias를 설정해준다.

{
  "settings": {
    "import/resolver": {
      "typescript": {
        "directory": "./src",
        "alias": {
          "@components": "./src/components"
        }
      }
    }
  }
}

깔끔한 해피 엔딩 ^~^

배포

이렇게 작성한 스토리북을 디자이너와 함께 보기 위해서는 어딘가에 배포를 해야되는데, Chromatic으로 이를 간편하게 할 수 있는 방법이 공식문서에 아주 자세하고 친절하게 잘 나와있다.

Chromatic에 깃헙으로 로그인해 나의 레포에 접근하고, 토큰과 명령어를 통해 바로 연결하고 배포할 수 있다.

yarn add -D chromatic

이후

yarn chromatic --project-token=<project-token>

를 하면 알아서 배포가 되고 크로마틱 페이지에서 확인할 수 있다.

참고로 난 storybook build 하는 단계에서

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

을 하니 자꾸 요런 에러가 났다.

yarn chromatic --project-token=토큰값

하면 에러가 안나는데.. 왜 npx 로 하면 에러가 나는걸까?

일단 우리는 스토리북이 필수가 아니고 선택적으로 사용하기로 했기 때문에, CI에 얹지 않고 수동 스크립트로 실행될 수 있게끔 package.json에 스크립트를 추가해주었다.

환경 변수 설정하기

package.json에 프로젝트 토큰이 노출되면 안되므로, env에 숨겨주었다. package.json의 script 부분에 바로 변수를 지정하기 위해 다음과 같이 설정해주었다.
(CI에 연결하는 경우 github secret에 추가해주면 됨!)

아래 라이브러리를 설치해주었다

$ yarn add -D dotenv-cli
$ yarn add -D cross-var

.env 파일을 생성해 키를 넣어주고

CHROMATIC_PROJECT_TOKEN=값

.gitignore에도 추가해주었다.

#env
.env

package.json의 script를 이렇게 만들어주면 끝!

"chormatic": "dotenv -- cross-var chromatic --project-token=%CHROMATIC_PROJECT_TOKEN%"

dotenv -- cross-var 요게 꼭 추가되어야 읽을 수 있다!
참고한 포스팅

이제

$ yarn chromatic

하면 잘 배포 되는 것을 확인할 수 있다 ^~^

참고로 크로마틱을 도입해보니, 디자이너와 같이 변경된 컴포넌트에 대한 QA를 진행할 수 있고 Accept 또는 Deny를 할 수 있으며 피그마와 연동도 되어서 협업하기 정 말 좋을 듯 하다! 써보고 공유할 만한 부분이 많이 생기면 따로 포스팅 올리도록 하겠다. 안녕~~~