shkim4/HMDesign
Private
Public Access
1
0 Fork 0
Code Activity

docs: standardize Git submodule and workspace installation
Deploy Storybook / deploy (push) Successful in 1m12s

Browse Source
This commit is contained in:
shkim4 committed 2026-10-23 11:06:19 +09:00
1 parent 3a4c63b5a4
commit 89011a2e42
18 files changed
+51 -39
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/guidelines/external-install-submodule.md
+6 -4
View File
@@ -1,6 +1,6 @@
# 외부 프로젝트 설치 — Git Submodule + npm Workspace
> 2026-10-20 작성. 현재 HMDesign을 다른 React 프로젝트에서 쓰는 공식 방식입니다. npm Registry publish 없이 Git 저장소를 Submodule로 연결하고, HMDesign 안에서 패키지를 빌드한 뒤 소비 프로젝트의 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. 전제
@@ -9,7 +9,7 @@
|---|---|
| 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/b25027/HMDesign.git`)와 npm Registry 접근 필요 |
| 네트워크 | 최초 설치에 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 고정
@@ -17,7 +17,7 @@
소비 프로젝트 루트에서 실행합니다. `<검증 Commit>`은 사용할 HMDesign Commit의 전체 SHA입니다(브랜치 이름을 그대로 쓰지 않습니다).
```bash
git submodule add https://gitea.hmac.kr/b25027/HMDesign.git HMDesign
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
@@ -26,6 +26,7 @@ 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 안에서 설치·빌드
@@ -98,4 +99,5 @@ git commit -m "chore: update HMDesign to <새 검증 Commit>"
- `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 여부를 기록합니다.
- npm Registry publish는 현재 필수가 아닙니다. Registry 배포를 도입하면 이 문서와 별도로 [운영/배포 가이드](./운영-배포-가이드.md)에 절차를 둡니다.
- 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 등 운영 배포는 [운영/배포 가이드](./운영-배포-가이드.md)를 따릅니다.