NX 모노레포에 스토리북 설정하기
스토리북 설치 및 설정
NX 모노레포 환경에서 스토리북을 설정하는 과정을 설명합니다. 스토리북은 UI 컴포넌트를 독립적으로 개발하고 테스트할 수 있는 환경을 제공합니다.
1. 스토리북 패키지 설치
먼저 스토리북과 관련 패키지를 설치합니다:
npm install -D storybook @storybook/react @storybook/addon-essentials @storybook/addon-interactions @storybook/addon-links @storybook/blocks @storybook/builder-vite @storybook/react-vite --legacy-peer-deps주의사항: 스토리북 설치 시 의존성 충돌이 발생할 수 있습니다. 이 경우 --legacy-peer-deps 옵션을 사용하여 설치합니다.
2. 설치 중 발생한 오류
스토리북 설치 중 다음과 같은 오류가 발생했습니다:
npm error code ERESOLVE
npm error ERESOLVE could not resolve
npm error
npm error While resolving: nest-ui@1.0.0
npm error Found: storybook@8.6.14
npm error node_modules/storybook
npm error peer storybook@"^8.6.14" from @storybook/addon-essentials@8.6.14
npm error node_modules/@storybook/addon-essentials
npm error dev @storybook/addon-essentials@"*" from the root project
npm error peer storybook@"^8.6.14" from @storybook/addon-interactions@8.6.14
npm error node_modules/@storybook/addon-interactions
npm error dev @storybook/addon-interactions@"*" from the root project
npm error
npm error Could not resolve dependency:
npm error dev @storybook/addon-links@"*" from the root project
npm error
npm error Conflicting peer dependency: storybook@9.0.18
npm error node_modules/storybook
npm error peer storybook@"^9.0.18" from @storybook/addon-links@9.0.18
npm error node_modules/@storybook/addon-links
npm error dev @storybook/addon-links@"*" from the root project
이 문제는 스토리북 버전 간의 충돌로 인해 발생했습니다. 해결을 위해 동일한 버전의 스토리북 패키지를 설치했습니다:
npm install -D storybook@8.6.14 @storybook/react@8.6.14 @storybook/addon-essentials@8.6.14 @storybook/addon-interactions@8.6.14 @storybook/addon-links@8.6.14 @storybook/blocks@8.6.14 @storybook/builder-vite@8.6.14 @storybook/react-vite@8.6.14 --legacy-peer-deps3. 스토리북 초기화
스토리북을 초기화하기 위해 다음 명령어를 실행했습니다:
npx storybook init그러나 NX 프로젝트에서는 다음과 같은 오류가 발생했습니다:
SB_CLI_INIT_0001 (NxProjectDetectedError): We have detected Nx in your project. Nx has its own Storybook initializer, so please use it instead.
Run "nx g @nx/storybook:configuration" to add Storybook to your project.
4. NX 스토리북 설정
NX에서는 자체 스토리북 설정 도구를 제공합니다. 먼저 필요한 패키지를 설치합니다:
npm install -D @nx/storybook그 다음 UI 프로젝트에 스토리북을 설정합니다:
nx g @nx/storybook:configuration ui --tsConfiguration이 과정에서 몇 가지 질문에 답해야 합니다:
- 스토리북 인터랙션 테스트 설정 여부:
Y - 사용할 스토리북 프레임워크 선택:
@storybook/react-vite
주의사항: 프로젝트 경로가 아닌 프로젝트 이름을 지정해야 합니다. 예를 들어 packages/ui가 아닌 ui를 사용해야 합니다.
5. 설정 결과
스토리북 설정이 완료되면 다음과 같은 파일들이 생성됩니다:
packages/ui/.storybook/main.ts: 스토리북 메인 설정 파일packages/ui/.storybook/preview.ts: 스토리북 프리뷰 설정 파일packages/ui/tsconfig.storybook.json: 스토리북용 TypeScript 설정 파일
main.ts 파일의 내용은 다음과 같습니다:
import type { StorybookConfig } from '@storybook/react-vite';
const config: StorybookConfig = {
stories: ['../src/lib/**/*.@(mdx|stories.@(js|jsx|ts|tsx))'],
addons: [],
framework: {
name: '@storybook/react-vite',
options: {
builder: {
viteConfigPath: 'vite.config.ts',
},
},
},
};
export default config;컴포넌트 스토리 작성
1. 버튼 컴포넌트 스토리 생성
버튼 컴포넌트의 스토리를 생성하기 위해 다음 명령어를 사용할 수 있습니다:
nx g @nx/react:component-story --componentPath=src/lib/components/button/button.tsx --project=ui또는 직접 button.stories.tsx 파일을 생성할 수도 있습니다:
// packages/ui/src/lib/components/button/button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './button';
const meta: Meta<typeof Button> = {
component: Button,
title: 'UI/Button',
tags: ['autodocs'],
argTypes: {
variant: {
control: { type: 'select' },
options: ['primary', 'secondary', 'outline', 'text'],
description: '버튼 종류',
table: {
defaultValue: { summary: 'primary' },
},
},
size: {
control: { type: 'select' },
options: ['small', 'medium', 'large'],
description: '버튼 크기',
table: {
defaultValue: { summary: 'medium' },
},
},
},
};
export default meta;
type Story = StoryObj<typeof Button>;
export const Primary: Story = {
args: {
variant: 'primary',
children: '기본 버튼',
},
};
export const Secondary: Story = {
args: {
variant: 'secondary',
children: '보조 버튼',
},
};2. 카드 컴포넌트 생성 및 스토리 작성
카드 컴포넌트를 생성하고 스토리를 작성합니다:
nx g @nx/react:component card --project=ui --directory=lib/components/card
nx g @nx/react:component-story --componentPath=src/lib/components/card/card.tsx --project=ui스토리북 실행
스토리북을 실행하려면 다음 명령어를 사용합니다:
npx nx run ui:storybook이 명령어는 스토리북 개발 서버를 시작하고, 기본적으로 http://localhost:4400에서 접속할 수 있습니다.
주요 오류 및 해결 방법
1. 의존성 충돌 오류
오류 메시지:
npm error code ERESOLVE
npm error ERESOLVE could not resolve
해결 방법:
- 동일한 버전의 스토리북 패키지를 설치합니다.
--legacy-peer-deps옵션을 사용합니다.
2. NX 프로젝트 감지 오류
오류 메시지:
SB_CLI_INIT_0001 (NxProjectDetectedError): We have detected Nx in your project.
해결 방법:
- NX의 스토리북 설정 도구를 사용합니다:
nx g @nx/storybook:configuration ui --tsConfiguration
3. 프로젝트 경로 오류
오류 메시지:
Cannot find configuration for 'packages/ui'
해결 방법:
- 프로젝트 경로가 아닌 프로젝트 이름을 사용합니다:
ui대신packages/ui
4. 모듈 경로 오류
오류 메시지:
'@storybook/react' 모듈 또는 해당 형식 선언을 찾을 수 없습니다.
해결 방법:
- 스토리북 설정이 완료되면 해당 모듈이 자동으로 인식됩니다.
- 필요한 경우
tsconfig.json에 경로를 추가합니다.
5. 애드온 버전 문제
현제 기준 storybook 9.0.18 버전 애드온은 여기까지 지원하지 않기 때문에 의존성 문제가 발생합니다
npm install storybook@8.6.14@storybook/addon-essentials@8.6.14 @storybook/addon-interactions@8.6.14 @storybook/blocks@8.6.14 @storybook/core-server@8.6.14 @storybook/react@8.6.14 @storybook/react-vite@8.6.14 @storybook/addon-links@8.6.14 @storybook/builder-vite@8.6.14 --save-dev
npm warn ERESOLVE overriding peer dependency추가 패키지
npm install --save-dev @storybook/jest @storybook/testing-library --force결론
NX 모노레포 환경에서 스토리북을 설정하는 과정은 일반적인 React 프로젝트와는 다소 차이가 있습니다. NX는 자체 스토리북 설정 도구를 제공하며, 이를 통해 각 프로젝트별로 독립적인 스토리북 설정이 가능합니다.
특히 UI 컴포넌트 라이브러리에 스토리북을 설정하면 컴포넌트를 독립적으로 개발하고 테스트할 수 있어 개발 효율성이 크게 향상됩니다.
다음 단계
- 더 많은 컴포넌트 스토리 작성
- 스토리북 애드온 추가 (접근성, 뷰포트 등)
- 테마 전환 기능 구현
- 컴포넌트 문서화 개선
스토리북은 UI 컴포넌트 라이브러리의 개발과 문서화에 필수적인 도구이며, NX 모노레포 환경에서도 효과적으로 활용할 수 있습니다.