React 컴포넌트 라이브러리 배포와 문서화

개요

컴포넌트 재사용과 일관된 UI를 위해 라이브러리를 만들면 개발 속도가 빨라진다. 이 글에서는 react component library 제작 과정 전반을 소개한다. 초기 구조, 빌드 도구 선택, storybook react 문서화, 그리고 npm 패키지 배포 react 절차까지 실무 관점에서 정리한다.

프로젝트 구조와 초기 설정

권장 구조

단순한 구조가 유지보수에 유리하다. 보통 다음과 같은 디렉토리를 사용한다.

• src/ - 컴포넌트 소스
• stories/ - Storybook 스토리
• dist/ - 빌드 산출물
• package.json, tsconfig.json 등 설정 파일

의존성과 빌드 도구

타깃은 다른 프로젝트에서 설치 가능한 형태다. 보통 번들러로 Rollup 또는 Vite를 사용한다. TypeScript를 기본으로 하면 타입 제공이 편리하다. 외부 라이브러리는 peerDependencies로 지정해 충돌을 방지한다.

컴포넌트 작성 원칙

다음 원칙을 따르면 재사용성과 문서화가 쉬워진다.

• 단일 책임: 하나의 컴포넌트에 기능을 집중
• 스타일 격리: CSS-in-JS 또는 모듈화된 CSS 사용
• 타입 제공: TypeScript로 Prop 타입 명시
• 작은 예제와 스토리 작성: storybook react 문서화에 유리

Storybook으로 문서화하기

Storybook은 UI 컴포넌트를 시각화하고 테스트할 수 있게 해준다. 각 컴포넌트에 스토리를 추가하면 사용 예시와 props 설명을 함께 제공할 수 있다.

간단한 스토리 예

import React from 'react';
import { Button } from '../src/Button';

export default {
  title: 'Controls/Button',
  component: Button,
};

export const Primary = () => <Button variant="primary">Click</Button>;

위 예제의 <Button> JSX는 < 와 > 문자를 &lt; &gt;로 변환해 Storybook에서 안전하게 사용한다.

빌드와 번들링

라이브러리는 여러 환경에서 사용된다. CommonJS와 ES Module을 모두 지원하면 호환성이 좋다. Rollup 설정 예시는 아래와 같다.

Rollup 기본 설정

import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import typescript from '@rollup/plugin-typescript';

export default {
  input: 'src/index.ts',
  output: [
    { file: 'dist/index.cjs.js', format: 'cjs' },
    { file: 'dist/index.esm.js', format: 'esm' },
  ],
  external: ['react', 'react-dom'],
  plugins: [resolve(), commonjs(), typescript()],
};

패키지 준비와 배포

npm 패키지로 배포하기 전 다음을 확인한다.

• package.json의 main과 module 필드 설정
• 타입 선언 파일(.d.ts) 포함
• README와 라이선스 파일 존재

package.json 예

{
  "name": "@your-scope/ui-library",
  "version": "1.0.0",
  "main": "dist/index.cjs.js",
  "module": "dist/index.esm.js",
  "types": "dist/index.d.ts",
  "peerDependencies": {
    "react": "^16.8 || ^17 || ^18"
  }
}

npm 배포 명령 예

npm run build
npm publish --access public

사내 레지스트리를 사용하는 경우 별도 설정이 필요하다. npm 패키지 배포 react 과정에서는 버전 관리와 접근 권한 설정이 중요하다.

버전 관리와 CI 연동

자동 배포와 릴리즈는 실수를 줄인다. GitHub Actions나 GitLab CI로 다음을 자동화하면 좋다.

• 테스트 실행
• 빌드 및 아티팩트 생성
• semantic-release로 자동 버전 증가와 npm 배포

유지보수와 릴리즈 전략

명확한 변경 로그와 마이그레이션 가이드를 제공하면 소비자가 따라오기 쉽다. Breaking change는 Major 버전으로 관리하고, 패치와 마이너 변경은 규칙적으로 릴리즈한다.

마무리

react component library 제작은 설계에서 배포까지 단계가 많다. Storybook을 통한 시각적 문서화와 안정적인 빌드, npm 패키지 배포 react 절차를 갖추면 재사용성과 팀 협업이 크게 향상된다. 처음에는 작은 범위로 시작해 점진적으로 범위를 넓히는 방식을 권한다.