스토리북(Storybook)

UI 컴포넌트 개발을 위해 스토리북이 많이 사용되는 것 같다.

채용 공고에서도 유경험자를 자격요건으로 걸기에 나도 학습해 보았다.

(아래의 내용은 여러 경로를 통해 학습하고, 이해하게 된 내용)

 

스토리북이란?

스토리북은 UI 컴포넌트 가이드북이다.

• UI 컴포넌트의 디자인을 한눈에 볼 수 있다.
  ex) Primary 버튼, Secondary 버튼 등 버튼의 스타일 확인 가능
  
• UI 컴포넌트의 상태를 한눈에 볼 수 있다.
  ex) 버튼 컴포넌트의 다양한 상태(활성, 비활성, 클릭 상태 등) 확인 가능
  
  
• UI 컴포넌트가 가지고 있는 액션을 실행해 볼 수 있다.
  === 컴포넌트의 상태나 프로퍼티 변경에 따른 시각적 변화를 쉽게 관찰 가능
  
  
• UI 컴포넌트를 테스트하고, 디버깅할 수 있다.
  === 컴포넌트의 동작 확인, 디버깅 가능
  
  
• UI 컴포넌트를 문서화할 수 있다.
  === 컴포넌트의 사용법, 프로퍼티, 이벤트, 상태 전이 등의 레퍼런스 문서화 가능
  

 

 

그동안은 가이드 화면을 따로 구축했었는데

앞으론 스토리북을 이용하면 디자이너, 개발자도 쉽게 UI 컴포넌트를 확인할 수 있겠다.

그동안 만들었던 가이드 화면

---

스토리북 설치

설치 명령어

npx sb init

npx는 Node.js 패키지 실행기로 이 명령어를 사용하면 로컬 또는 원격 저장소에 있는 Node.js 패키지를 실행할 수 있다.

npx는 주로 프로젝트 종속성이나 스크립트를 실행할 때 사용된다.

최신 버전의 Storybook에서는 @storybook/cli 대신 npx sb 명령어를 사용하는 것이 권장된다.

새로운 방식은 "Zero-config"(무설정) 스토리북을 도입하며, 설정과 환경 구성을 자동화하고 개발자가 더 쉽게 스토리북을 설정할 수 있게 해준다.

npx sb 명령어를 실행하면 스토리북을 시작하고 필요한 종속성을 자동으로 설치한다.

 

실행 명령어

npm run storybook

실행하면 6006 포트로 화면이 띄워진 것을 볼 수 있다.

---

폴더 구조

최초 설치하면, 설정 파일들을 모아놓은 .storybook 폴더와 스토리 파일들을 모아놓은 stories 폴더가 생성된다.

 

📂 .storybook

• main.js
  ➡️ 스토리북의 주요 구성 파일로, 프로젝트 설정과 스토리북 환경을 정의하는 데 사용
• preview.js
  ➡️ 스토리북의 미리 보기 설정 파일로, 스토리북 UI의 테마 및 기타 환경 설정을 정의하는 데 사용
• 기타 사용자 지정 파일 및 설정 파일을 추가할 수 있다.

📂 stories

• Configure.dx
  ➡️ Storybook 소개에 대한 내용과 사용 방법에 대한 내용이 나와있다.
  
  
• 스토리.jsx (리액트)
  ➡️ UI 컴포넌트 내용 추가
  
  
• 스토리.stories.js
  ➡️ 스토리 화면 정의, 스토리 속성 정의 등 스토리의 전반적인 선언 추가

---

사용 방법

npx sb init으로 설치를 했을 때, 샘플로 들어있는 파일과 스토리북 공식 사이트에서 튜토리얼로 제공되는 내용이 미묘하게 달랐다.

프레임워크 사용 여부의 차이 같다.

어떤 환경에서 작업할지 모르니 둘 다 분석해 보았다.

 

npx sb init 설치

// Button.jsx
// Button 컴포넌트 생성
export const Button = ({ primary, backgroundColor, size, label, ...props }) => {
	return (
		<button>...</button>
	);
};

// Button 컴포넌트에서 사용하는 속성(prop) 값 타입 선언
Button.propTypes = {
	primary: PropTypes.bool,
	backgroundColor: PropTypes.string,
	size: PropTypes.oneOf(['small', 'medium', 'large']),
	label: PropTypes.string.isRequired,
	onClick: PropTypes.func,
};

// Button 컴포넌트 속성(prop)의 기본 값 선언
Button.defaultProps = {
	backgroundColor: null,
	primary: false,
	size: 'medium',
	onClick: undefined,
};



// Button.stories.js
// 스토리 설정 값 선언
export default {
	title: 'Example/Button', // 사이드바 참조 값
	component: Button, // 사용 컴포넌트
	parameters: { // 스토리가 스토리북 화면 영역에서 어떻게 배치되는지를 정의
		layout: 'centered', // 버튼 컴포넌트를 화면 중앙에 배치하도록 설정
	},
	tags: ['autodocs'], // 컴포넌트 사용법 요약 Doc 생성 여부 설정
	argTypes: { // 속성(prop)을 편집하고 조작하는 방법을 정의
		backgroundColor: { control: 'color' }, // 색상 선택기 컨트롤로 조절할 수 있도록 설정
	},
};

// 스토리 정의
export const Primary = {
	args: {
		primary: true,
		label: 'Button',
	},
};

export const Warning = {
	args: {
		primary: true,
		label: 'Delete now',
		backgroundColor: 'red',
	},
};

 

스토리북 공식 사이트 튜토리얼

// Button.jsx
// Button 컴포넌트 생성
export const Button = ({ primary, backgroundColor, size, label, ...props }) => {
	return (
		<button>...</button>
	);
};



// Button.stories.js
// 스토리 설정 값 선언
export default {
	component: Button,
	title: 'Example/Button',
	tags: ['autodocs'],
};

// 템플릿 함수 정의
const Template = (args) => <Button {...args} />;

export const Default = Template.bind({});
Default.args = {
    primary: true,
    label: 'Button1',
};

// 스토리에 템플릿 함수 연결한 후, 스토리 정의
export const Warning = Template.bind({});
Warning.args = {
    primary: true,
    label: 'Delete now',
    backgroundColor: 'red',
};

두 소스의 다른 점은

propTypes를 이용해 속성(prop) 값 타입 선언 여부와 defaultProps를 이용해 속성(prop)의 기본 값을 선언 여부도 있지만

Template 함수를 만드느냐 안 만드느냐의 차이가 크다.

첫번째 방법만 보았을 땐, 대상 컴포넌트가 없는데 스토리가 적용되는 게 잘 이해 가지 않았다.

그래서 열심히 찾아보니...

 

첫 번째 방법은 스토리 파일에서 컴포넌트와 스토리를 같은 파일에 정의하는 방식으로

args 객체를 사용하여 초기 속성을 정의하고, 스토리 내에서 컴포넌트를 직접 렌더링하는 방식이다.

 

두 번째 방법은 Template 함수를 정의하고, 이 함수를 사용하여 컴포넌트를 스토리에 연결(bind) 하는 방식으로

템플릿 함수를 사용하여 컴포넌트를 렌더링하고, args 속성을 설정하여 컴포넌트에 초기 속성을 전달하는 방식이다.

 

첫 번째 방법은 CSF (Component Story Format) 기반으로, 스토리북 (Storybook)의 스토리를 정의하는 표준 형식 또는 스펙이다.

컴포넌트와 스토리를 같은 파일에 정의해 주면 스토리북이 따로 설정하지 않아도(Zero-config) 스토리북에서 알아서 렌더링 해준다.

[CSF 특징]

• 같은 파일에 스토리 정의
• 내보내기와 모듈 시스템 활용
• export를 통한 스토리 정의
• 자동 문서화(Autodocs) 지원

---

이제 내 프로젝트에 지정해 볼까! 하!