기여 가이드

lh-ui-plus에 기여해 주셔서 감사합니다! 이 문서는 자세한 기여 프로세스를 안내합니다.

사전 조건

• Node.js 18+
• pnpm으로 의존성 설치
• Git 기본 조작

의존성 설치

git clone https://github.com/lhgb-top/lh-ui-plus.git
cd lh-ui-plus
pnpm install

개발 흐름

1. 개발 서버 시작

pnpm dev

2. 테스트 실행

pnpm test:unit      # Core 레이어 단위 테스트
pnpm test:components  # 컴포넌트 통합 테스트
pnpm test            # 전체 테스트

3. 타입 검사

pnpm typecheck

4. 린트

pnpm lint
pnpm lint:fix       # 자동 수정

5. 빌드

pnpm build

6. 문서 확인

pnpm docs:dev

새 컴포넌트 추가

전체 프로세스는 AGENTS.md의 "Adding or changing a component" 섹션을 참고하세요.

간략한 단계:

1. @lh-ui/share의 src/core/<name>/ — 핵심 로직 + 단위 테스트 (share 저장소에서 완료하며, 이 저장소에서는 npm 의존성으로 사용)
2. packages/components/<name>/ — Vue 컴포넌트 래핑
3. packages/components/index.ts — lhComponents에 등록
4. src/index.ts — 내보내기 업데이트
5. tests/unit/components-registry.spec.ts — 기대값 배열 업데이트
6. tests/components/<name>.spec.ts — 컴포넌트 테스트
7. docs/components/<name>.md — 문서 페이지
8. docs/.vitepress/config.ts — 사이드바 내비게이션

검증 명령:

pnpm lint          # 0 errors, 0 warnings
pnpm typecheck     # 출력 없음
pnpm vitest run    # 전체 케이스 통과
pnpm docs:build    # 통과

문서 사이트 배포

문서 사이트의 배포 경로는 docs/.env.production에서 중앙 집중적으로 구성합니다 (단일 데이터 소스). 프로덕션 빌드는 다음과 같이 실행합니다:

pnpm docs:build

환경 변수	설명	기본값	예시
DOCS_BASE	사이트 base 경로, 양끝에 슬래시가 필요	/	/lhui/vue3/
DOCS_HOSTNAME	사이트 정식 도메인, sitemap과 SEO meta에 사용	https://www.lhgb.top	https://your-site.com

이 두 변수는 리소스 경로, sitemap, og:url 등 SEO 태그, 그리고 빌드 마지막에 다시 생성되는 robots.txt에 모두 적용됩니다.

.env에 두는 이유: Vite의 내장 env 로드는 사용자 config 평가 이후에 일어나기 때문에, docs/.vitepress/config.ts는 프로덕션 빌드 시 이 값을 읽으려면 명시적으로 loadEnv를 호출해야 합니다. 또한 Windows Git Bash의 MSYS는 인라인 변수 DOCS_BASE=/lhui/vue3/를 로컬 절대 경로로 자동 변환해 버립니다. 임시 덮어쓰기는 인라인 변수(DOCS_BASE=/xxx/ pnpm docs:build)도 가능하지만, 일상적인 배포에서는 .env.production을 수정하는 것이 더 안정적입니다.

통일된 게시 접두사 규칙

风默门户(www.lhgb.top)의 LH-UI 컴포넌트 라이브러리 내비게이션 페이지(/ui)는 각 컴포넌트 라이브러리 문서 사이트의 배포 경로를 **/lhui/{라이브러리명}/**으로 통일하며, 프레임워크 이름과 연결하지 않습니다. 이 라이브러리 (Vue 3 버전)는 **/lhui/vue3/**에 배포됩니다 (docs/.env.production에 기록됨). 프로덕션 빌드 명령:

pnpm docs:build

빌드 결과물은 서버 /home/webuser/nginx/lh-ui/vue3/에 업로드됩니다 (Nginx location 조각의 권위 있는 참고 복사본은 패밀리 docs/部署/nginx-lhui.conf.md에 있으며, 실 서버의 원본은 /etc/nginx/conf.d/nginx.conf입니다). 패밀리 8개 사이트는 모두 이 규칙에 따라 배포되었습니다:

저장소	base	alias 디렉터리	cleanUrls
lh-ui-plus (이 라이브러리)	/lhui/vue3/	/home/webuser/nginx/lh-ui/vue3/	아니오
lh-ui-vue2	/lhui/vue2/	/home/webuser/nginx/lh-ui/vue2/	아니오 (VuePress 1.x)
lh-ui-react	/lhui/react/	/home/webuser/nginx/lh-ui/react/	아니오
lh-ui-uniapp	/lhui/uniapp/	/home/webuser/nginx/lh-ui/uniapp/	예
lh-ui-android	/lhui/android/	/home/webuser/nginx/lh-ui/android/	예
lh-ui-ios	/lhui/ios/	/home/webuser/nginx/lh-ui/ios/	예
lh-ui-harmony	/lhui/harmony/	/home/webuser/nginx/lh-ui/harmony/	예
lh-ui-windows	/lhui/windows/	/home/webuser/nginx/lh-ui/windows/	예

네이티브 혈통의 4개 사이트 (android / ios / harmony / windows)는 VitePress 사이트에 내장된 정적 HTML 시뮬레이터이며, 배포 방식은 web 혈통의 4개 사이트와 완전히 동일합니다. 새 라이브러리도 /lhui/{라이브러리명}/ 규칙에 따라 각각 location과 .env.production을 확장합니다.

cleanUrls 사이트 (uniapp 및 네이티브 4개 사이트)의 Nginx try_files에는 반드시 $uri.html이 포함되어야 하며, 그렇지 않으면 확장자 없는 URL이 사전 렌더링된 .html을 찾지 못합니다. cleanUrls가 아닌 사이트에는 이 항목이 필요 없습니다. 참고 복사본의 「세 가지 계약」 섹션을 참고하세요.

코드 규칙

• CSS 클래스는 lh- 접두사 사용 (예: lh-button__text--primary)
• Composables는 반드시 Lh 접두사 사용 (예: useLhConfigProvider)
• 상수 객체는 반드시 모두 대문자 스네이크 케이스 사용 (예: LH_TYPES_CONST)
• 경로 별칭: ~/* → packages/* (이 저장소). 프레임워크와 무관한 로직과 스타일은 @lh-ui/share에 있으며, npm 서브패스 임포트 (@lh-ui/share/core/*, @lh-ui/share/styles/*)로 사용
• 포맷팅: 작은따옴표, 세미콜론 없음, 2칸 들여쓰기, 100자 줄 너비

커밋 규칙

feat: Select 드롭다운 선택 컴포넌트 추가
fix: Input 포커스 유실 문제 수정
docs: 설치 문서 업데이트
test: Button 경계 테스트 추가
refactor: ConfigProvider 반응형 로직 리팩터링

AI 보조 규칙

이 프로젝트는 AI agent의 보조를 받아 유지 관리됩니다. 검증 명령은 사용자가 수동으로 실행하며, AI가 자동으로 테스트/빌드를 실행하지 않습니다.