dwg-dxf-viewer-sample/docs/deploy-dist2-static-build.md

dist2 정적 빌드 배포 절차

항목	내용
작성 목적	Slug GPU 텍스트 cap-height 수정 배포 작업을 기록하고, 공식 배포 스크립트가 없는 이 저장소에서 재사용 가능한 절차로 남김
배포 대상	dist2/ (저장소에 커밋되는 정적 빌드 산출물, 실제 서빙 디렉터리)
계기 커밋	fb8f7ca fix(viewer2d): correct Slug GPU text scale to match DWG cap-height
배포일	2026-08-04
상태	완료 (origin/master push 완료)

---

1. dist2란 무엇인가

이 저장소는 공식 배포 스크립트가 없다. package.json에는 dev / build (→ dist/, .gitignore 대상) / preview / typecheck 뿐이고, dist2를 만드는 스크립트나 CI는 존재하지 않는다.

그런데도 dist2/는 저장소에 커밋되어 있고 (git ls-files dist2 로 확인 가능), 과거 커밋들(3d3e052 등)에서 반복적으로 갱신되어 온 정황으로 볼 때 vite build를 수동으로 --outDir dist2 옵션과 함께 실행해 만든 산출물을 그대로 커밋 → push 하는 방식이 이 프로젝트의 사실상 배포 방식이다.

src/  ──(vite build)──▶  dist/   (gitignore, 로컬 전용)
src/  ──(vite build --outDir dist2)──▶  dist2/  (git 커밋, 실제 배포물)

dist2/samples/, dist2/fonts/, dist2/docs/는 public/의 사본 + 빌드시 자동 복사분이다.

함정: dist2에 소스가 아닌 파일이 섞여 있다

배포 작업 시작 시 git status에 다음 untracked 파일이 있었다:

dist2/samples/configBak/   (cuiBak.cui, regBak.json — AutoCAD 설정 백업, 테스트용)
dist2/samples/dwg_18.3mb.dwg   (대용량 테스트 도면)

이 파일들은 public/samples/에 없다 → 빌드가 만든 게 아니라 사람이 dist2에 직접 넣어둔 테스트 자료다. Vite의 기본 emptyOutDir는 outDir가 프로젝트 루트 안에 있으면 true(빌드 전 디렉터리 전체 삭제)이므로, 아무 옵션 없이 vite build --outDir dist2를 돌리면 이 파일들이 삭제된다.

→ 배포 시 반드시 --emptyOutDir false를 붙인다 (아래 3절).

---

2. 사전 확인

cd D:\MYCLAUDE_PROJECT\dwg-dxf-viewer-sample
git status --short          # untracked/미커밋 상태 파악 (dist2 안 이물질 포함)
npx tsc --noEmit -p .       # 타입체크 먼저 (build 스크립트가 어차피 포함하지만 분리 확인)

npx vite ...가 이 환경에서 npm error Missing script: "vite"로 실패하는 경우가 있었다 (원인 미상 — npx가 로컬 bin 대신 npm script를 찾으려 한 것으로 보임). 재현되면 로컬 바이너리를 직접 호출:

./node_modules/.bin/vite build --outDir dist2 --emptyOutDir false

---

3. 빌드

cd D:\MYCLAUDE_PROJECT\dwg-dxf-viewer-sample
./node_modules/.bin/vite build --outDir dist2 --emptyOutDir false

• --outDir dist2: 기본 dist/(gitignore) 대신 커밋 대상 디렉터리로 출력
• --emptyOutDir false: 필수. dist2/samples/configBak/, dwg_18.3mb.dwg 등 빌드가 모르는 파일을 보존
• 결과: 새 해시가 붙은 assets/index-*.js, assets/acadrust_dwg_bg-*.wasm 등이 추가로 생기고, 예전 해시 파일은 자동 삭제되지 않음 (이 저장소의 기존 관행과 동일 — dist2/assets에 여러 세대의 index-*.js가 누적돼 있음). 이번 배포에서도 정리하지 않았다.
• dist2/index.html이 새 해시를 가리키도록 갱신됨

이번 실행 결과:

dist2/index.html                            10.88 kB
dist2/assets/acadrust_dwg_bg-Dt2ifJSA.wasm  879.93 kB
dist2/assets/acadrustParser-CJeZuNZe.js       4.18 kB
dist2/assets/index-CmUgC68r.js             1000.36 kB

---

4. 변경분 검토 (커밋 전 필수)

git status --short dist2 src
git diff dist2/index.html   # 새 해시 참조로만 바뀌었는지 확인

빌드 직전 dist2/index.html이 커밋 199317d(Entity 선택/Property/Layer 패널) 이전 상태를 가리키고 있었다 — 즉 이번 배포 전까지 dist2가 여러 커밋만큼 stale했다. git diff 결과 UI 패널 CSS/마크업 100줄+ 이 새로 반영된 것으로 확인, 이번 빌드가 그 gap을 포함해 최신화했다.

---

5. 스테이징 — 빌드 산출물만, 이물질 제외

git add src/viewer2d/slugText.ts \
        dist2/index.html \
        dist2/assets/acadrustParser-CJeZuNZe.js \
        dist2/assets/acadrust_dwg_bg-Dt2ifJSA.wasm \
        dist2/assets/index-CmUgC68r.js
git status --short   # dist2/samples/configBak/, dwg_18.3mb.dwg 는 untracked 로 남아있어야 함

git add dist2 나 git add -A를 쓰지 않는다 — configBak/, 대용량 테스트 .dwg가 함께 커밋되는 것을 막기 위함.

---

6. 커밋 & 푸시

git commit -m "fix(viewer2d): correct Slug GPU text scale to match DWG cap-height

..."
git push origin master

• push는 공유 원격(gitea origin)에 영향을 주는 되돌리기 어려운 작업 → 사용자 확인 후 실행했다.
• 결과: fb8f7ca 커밋으로 push 완료.

---

7. 체크리스트 (다음 배포 시 재사용)

• git status --short — dist2 안 untracked 이물질 있는지 먼저 확인
• tsc --noEmit 통과
• ./node_modules/.bin/vite build --outDir dist2 --emptyOutDir false (npx가 실패하면 이 경로로)
• git diff dist2/index.html 로 해시/마크업 변경분 확인
• git status --short dist2 로 새로 생긴 assets/* 해시 파일 목록 확인
• 필요한 파일만 개별 git add (샘플/백업 이물질 제외)
• 커밋 메시지에 무엇/왜 남김
• push 전 사용자 확인 (원격 공유 저장소)

---

8. 후속 과제

1. 공식 배포 스크립트 부재 — package.json에 "build:dist2": "vite build --outDir dist2 --emptyOutDir false" 같은 스크립트를 추가하면 --outDir/--emptyOutDir 플래그를 매번 손으로 맞출 필요가 없어진다.
2. 누적된 구세대 해시 파일 — dist2/assets/index-*.js가 세대별로 계속 쌓여만 있다 (정리 안 됨). 정리하려면 배포 직후 dist2/index.html이 참조하지 않는 해시 파일을 찾아 지우는 스텝이 필요하나, 이번 배포에서는 기존 관행을 바꾸지 않기 위해 손대지 않았다.
3. dist2 안 테스트 이물질(configBak/, dwg_18.3mb.dwg) — 배포 산출물 디렉터리에 테스트 자료가 섞여 있는 구조 자체가 위험(다음 사람이 무심코 emptyOutDir 기본값으로 밀어버릴 수 있음). public/samples/ 같은 소스 디렉터리로 옮기거나 별도 경로 분리를 검토할 것.

---

9. 참고

• 빌드 산출물: ../dist2/
• Vite 설정: ../vite.config.ts
• 이번 배포로 반영된 수정: ../src/viewer2d/slugText.ts
• 관련 배포(원인 무관, 이후 별도 push로 dist2 추가 갱신됨): 3480945 perf(viewer2d): toggle layers by visibility instead of reloading the drawing