shkim4/HMDesign
Private
Public Access
1
0 Fork 0
Code Activity
Files
db03e155ddc8847265b0ab476460be7c36c2917a
HMDesign/docs/guidelines/external-install-submodule.md
T
shkim4 89011a2e42
Deploy Storybook / deploy (push) Successful in 1m12s
docs: standardize Git submodule and workspace installation
2026-10-23 11:06:19 +09:00

7.3 KiB
Raw Blame History

외부 프로젝트 설치 — Git Submodule + npm Workspace

2026-10-20 작성, 2026-10-23 갱신(저장소 주소 shkim4, HM 패키지 npm Registry 미사용 명시). 현재 HMDesign을 다른 React 프로젝트에서 쓰는 공식 방식입니다. npm Registry publish 없이 Git 저장소를 Submodule로 연결하고, HMDesign 안에서 패키지를 빌드한 뒤 소비 프로젝트의 npm Workspace로 연결합니다. 실제 적용 근거: 외부 DWG/DXF Viewer(React 19, @hm-design/ui + @hm-design/sw)가 이 절차로 연결되었습니다. 패키지 tarball 소비 검증은 packages/sw/tests/integrated-consumer.mjs가 별도로 수행합니다.

1. 전제

항목 기준
Node.js / npm package-lock.json의 엔진 조건 ^20.19.0 || >=22.12.0(Node 21 제외). 검증 기록: Node 20.20.1 / npm 10.8.2(2026-10-11), Node 22.23.2 / npm 10.9.8(2026-10-20)
React 소비 프로젝트 react·react-dom ^19.0.0(모든 패키지의 peer)
네트워크 최초 설치에 Gitea(https://gitea.hmac.kr/shkim4/HMDesign.git)와 외부 dependency용 공개 npm Registry(registry.npmjs.org) 접근 필요. HM 패키지용 Gitea npm Registry·.npmrc 설정은 쓰지 않음
Git 패키지 dist/는 Git에 포함되지 않습니다(.gitignore). Clone·Commit 변경 후에는 항상 HMDesign 안에서 다시 빌드합니다.

2. Submodule 연결과 검증 Commit 고정

소비 프로젝트 루트에서 실행합니다. <검증 Commit>은 사용할 HMDesign Commit의 전체 SHA입니다(브랜치 이름을 그대로 쓰지 않습니다).

git submodule add https://gitea.hmac.kr/shkim4/HMDesign.git HMDesign
git -C HMDesign fetch origin
git -C HMDesign checkout <검증 Commit>
git add .gitmodules HMDesign
git commit -m "chore: pin HMDesign <검증 Commit>"
  • 소비 프로젝트에 기록되는 것은 Submodule Commit 포인터입니다. 다른 사람·CI는 git submodule update --init --recursive로 같은 Commit을 받습니다.
  • Submodule 안에서 HMDesign 파일을 직접 수정하지 않습니다. git status에 HMDesign (modified content) / -dirty가 보이면 고정 Commit과 다른 코드로 빌드된 상태입니다. 그 상태의 검증 결과는 해당 Commit의 결과로 보고하지 않습니다.
  • 이전 주소(https://gitea.hmac.kr/b25027/HMDesign.git)로 연결한 Submodule은 리다이렉트로 동작하지만 현재 주소로 바꿉니다. git submodule set-url HMDesign https://gitea.hmac.kr/shkim4/HMDesign.git → git submodule sync → .gitmodules Commit. Submodule Commit 포인터와 npm ci·빌드 절차는 바뀌지 않습니다.

3. HMDesign 안에서 설치·빌드

git submodule update --init --recursive
cd HMDesign
npm ci
npm run build:packages
cd ..
  • npm ci는 HMDesign 자체 빌드 도구(Vite·TypeScript·Tailwind 등)를 HMDesign/node_modules에 설치합니다. 패키지 빌드 스크립트가 이 위치의 도구를 사용하므로 생략할 수 없습니다.
  • build:packages는 org-chart → ui → center-graphic → org-chart-react → sw 순서로 5개 패키지의 dist/를 만듭니다. 필요한 패키지만 빌드할 때는 npm run build:ui, npm run build:sw를 쓸 수 있고, org-chart-react는 org-chart를 먼저 빌드해야 합니다.

4. 소비 프로젝트 Workspace 연결

소비 프로젝트 package.json에 사용할 패키지만 Workspace와 dependency로 추가합니다.

{
  "workspaces": ["HMDesign/packages/ui", "HMDesign/packages/sw"],
  "dependencies": {
    "@hm-design/ui": "*",
    "@hm-design/sw": "*",
    "react": "19.3.0",
    "react-dom": "19.3.0"
  }
}

npm install
  • npm install 후 node_modules/@hm-design/<패키지>는 HMDesign/packages/<패키지>를 가리키는 링크입니다. Import는 패키지 exports의 공개 진입점만 사용합니다(dist·src 내부 경로 금지).
  • OrgChart를 쓰면 HMDesign/packages/org-chart(와 React에서는 HMDesign/packages/org-chart-react)를 추가합니다.
  • Vite 소비 프로젝트는 HMDesign 저장소 안의 예제·Export용 HTML을 의존성 스캔에서 제외하도록 optimizeDeps.entries: ['index.html']를 지정합니다(외부 Viewer에서 확인된 설정).

5. CSS Import

패키지 앱 진입점
Web @hm-design/ui CSS entry에서 @import "tailwindcss"; → @import "@hm-design/ui/tailwind.css"; → @import "@hm-design/ui/theme.css";. Tailwind 검색 범위는 Runtime portability를 따릅니다.
SW @hm-design/sw import "@hm-design/sw/styles.css"를 한 번. JS import만으로 CSS가 들어오지 않습니다. 글꼴 파일은 포함하지 않습니다(기본 Noto Sans KR).
OrgChart Core CSS 두 개(@hm-design/org-chart/engine.css, @hm-design/org-chart/style.css)를 URL로 해석해 stylesheetUrls에 전달합니다(Shadow DOM). 문서에 import하는 것만으로는 적용되지 않습니다.

Web과 SW를 함께 쓰면 두 CSS의 순서는 서로의 계산 스타일을 바꾸지 않습니다(integrated-consumer 검증 항목).

6. AI 지침 탐색

  • 소비 프로젝트의 AI 코딩 도구는 node_modules/@hm-design/<패키지>/ai/(= HMDesign/packages/<패키지>/ai/)를 읽습니다. 진입점은 각 폴더의 AI_GUIDE.md이며 사용 유형(Web / SW 일반·뷰어 / OrgChart / 혼합)을 먼저 정합니다.
  • 루트 AGENTS.md·CLAUDE.md는 자동으로 연결되지 않습니다. ai/AGENTS_SNIPPET.md의 문구를 소비 프로젝트 루트 지침에 붙입니다(방법은 AI_GUIDE.md의 "소비 프로젝트 설정").
  • HMDesign 저장소 루트의 AGENTS.md·CLAUDE.md는 HMDesign을 개발하는 AI용이며 소비 프로젝트 지침이 아닙니다.

7. HMDesign 버전 갱신

git -C HMDesign fetch origin
git -C HMDesign checkout <새 검증 Commit>
cd HMDesign && npm ci && npm run build:packages && cd ..
npm install
git add HMDesign
git commit -m "chore: update HMDesign to <새 검증 Commit>"

갱신 후 소비 프로젝트의 Typecheck·Build·화면 확인을 다시 실행합니다.

8. Registry 없이 사용할 때의 제약

  • dist/가 Git에 없으므로 Clone·Commit 변경·CI마다 HMDesign 빌드(§3)가 필요합니다. CI에서도 Submodule 초기화와 npm ci && npm run build:packages를 실행합니다.
  • HMDesign 빌드 도구와 소비 프로젝트 도구가 따로 설치됩니다(예: 외부 Viewer는 TypeScript 5.9·Vite 5, HMDesign은 TypeScript 7·Vite 8). 패키지는 HMDesign 도구로 빌드되고 소비 프로젝트는 결과물만 사용합니다.
  • 버전 식별은 Submodule Commit SHA입니다. SW 패키지는 dist/build-info.json에 빌드한 Commit과 dirty 여부를 기록합니다.
  • HM 패키지는 npm Registry로 배포하지 않습니다. npm install @hm-design/<패키지>@<버전>으로 설치하거나 .npmrc에 @hm-design:registry를 추가하지 않습니다. 2026-10-07 Gitea npm Registry에 시험 게시한 @hm-design/ui@0.1.0·@hm-design/center-graphic@0.1.0은 현재 소스와 다른 이전 산출물입니다.
  • package.json의 version(예: 0.1.0)은 Workspace 연결과 peer 범위용 값이며 Registry 배포 버전이 아닙니다. Theme CDN 등 운영 배포는 운영/배포 가이드를 따릅니다.
View Git Blame Copy Permalink