28-feature-패키지-번들링-최적화

[sooster910]

항목	내용
🔗 관련 이슈	#28 패키지 번들링 최적화
🏷️ 작업 타입	Chore / Build Optimization
📦 변경 범위	react-button 패키지

배경 (Problem)

• react-button, react-heading 등 현재 배포된 패키지들이 tailwind-merge, clsx를 번들에 포함하고 있어 라이브러리 번들 크기가 불필요하게 커집니다. 패키지 크기: unpacked 92.4KB - 단일 컴포넌트 라이브러리치고 과도하게 큰 크기
• 사용자 프로젝트가 이미 같은 의존성을 사용 중이면 최종(앱) 번들에 중복으로 포함되어 전체 번들 크기가 증가합니다.
• clsx는 클래스 결합만 처리하지만 Tailwind의 우선순위/충돌 해결(예: twMerge)을 하지 못하므로 tailwind-merge 사용이 필요합니다.

원인분석

번들 크기 92.4KB 구성 분석에서 2000 줄이 넘는 tailwind-merge 가 전체 크기의 89% 차지

주요 변경사항

번들 크기 최적화 코드라인 : 2015→ 총 147 lines (-93%), unpacked 92.4kb → 13.5kb(-85%)

• 외부 의존성 분리: clsx, tailwind-merge를 peer dependencies로 이동
• rollupOptions 설정

왜 external 처리가 필요한가?
peerDependencies로만 지정하면 패키지 설치 시 소비자가 해당 모듈을 설치해야 한다는 사실만 보장합니다.
하지만, 빌드 단계에서 별도로 external로 지정하지 않으면 번들러는 여전히 해당 모듈을 라이브러리 번들 안에 포함시켜 버릴 수 있습니다.

이를 방치하면 다음 문제가 발생합니다:

1. 번들 크기 증가

• clsx, tailwind-merge 같은 유틸리티가 라이브러리 번들에 포함되어 불필요하게 커짐.

2. 중복 의존성 문제

• 소비자 앱에서 이미 같은 라이브러리를 설치했을 경우, 최종 앱 번들에 중복 포함 → 불필요한 자원 낭비.

3. 버전 충돌 / 다중 인스턴스 문제

우리 라이브러리가 특정 버전의 clsx를 내장하고 있으면, 사용자 프로젝트가 다른 버전 clsx를 쓰고 있을 때 React Tree 안에서 서로 다른 clsx 인스턴스가 존재하게 되고 함수 레벨 유틸이라도 유지보수성 문제를 일으킬 수 있습니다. external로 처리하면 항상 사용자 프로젝트에서 설치한 단일 인스턴스만 존재하게 되어 안전합니다. 같은 맥락으로 clsx나 tailwind-merge도 프로젝트마다 다른 버전이 충돌할 수 있습니다.

• 번들 분석 도구 추가: rollup-plugin-visualizer를 통한 번들 크기 모니터링
• 번들 분석 스크립트: analyze.js 추가로 번들 크기 추적 가능

리스크 & 대응

1. 사용자가 peer deps를 설치하지 않음

• 영향: 런타임에서 모듈 미존재로 에러 발생 가능
• 대응: README에 명확한 설치 가이드 추가, 패키지 사용 시 친절한 에러 메시지(빌드 시 경고 스크립트 또는 런타임에서 설치 유무 체크 후 경고) 도입 고려

2. 버전 호환성 이슈

• 대응: peerDependencies에 버전 범위를 명시, 마이그레이션 가이드 제공