minsungandClaude Opus 5
6f200ef692
This repository has no deploy script or CI: package.json only builds to
dist/ (gitignored), yet dist2/ is committed and is what actually gets
served. The procedure was folklore reconstructed from commit history each
time someone deployed.
Write it down, including the two traps found while deploying fb8f7ca:
- vite's emptyOutDir defaults to true when outDir sits inside the project
root, so a bare `vite build --outDir dist2` deletes the hand-placed test
assets in dist2/samples (configBak/, dwg_18.3mb.dwg). Always pass
--emptyOutDir false.
- npx vite can fail here with `Missing script: "vite"`; call
./node_modules/.bin/vite directly.
Also notes the open issues: no build:dist2 script, old hashed bundles
accumulating in dist2/assets, and test fixtures living inside the build
output directory.
Link it from the README issue table.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
147 lines
7.1 KiB
Markdown
147 lines
7.1 KiB
Markdown
# `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. 사전 확인
|
|
|
|
```bash
|
|
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를 찾으려 한 것으로 보임). 재현되면 로컬 바이너리를 직접 호출:
|
|
|
|
```bash
|
|
./node_modules/.bin/vite build --outDir dist2 --emptyOutDir false
|
|
```
|
|
|
|
---
|
|
|
|
## 3. 빌드
|
|
|
|
```bash
|
|
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. 변경분 검토 (커밋 전 필수)
|
|
|
|
```bash
|
|
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. 스테이징 — 빌드 산출물만, 이물질 제외
|
|
|
|
```bash
|
|
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. 커밋 & 푸시
|
|
|
|
```bash
|
|
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/`](../dist2/)
|
|
- Vite 설정: [`../vite.config.ts`](../vite.config.ts)
|
|
- 이번 배포로 반영된 수정: [`../src/viewer2d/slugText.ts`](../src/viewer2d/slugText.ts)
|
|
- 관련 배포(원인 무관, 이후 별도 push로 `dist2` 추가 갱신됨): `3480945` perf(viewer2d): toggle layers by visibility instead of reloading the drawing
|