단일 HTML 파일 기반 도구를 어떻게 설계·운영하는가 ("Useful patterns for building HTML tools")
📝 Document 요약 및 번역
— 단일 HTML 파일로 만드는, 가장 빠른 생산성 도구 설계법
Simon Willison은 지난 2년간 150개 이상의 ‘HTML tools’를 만들었다.
공통점은 명확하다.
- HTML + JS + CSS 단일 파일
- 빌드 스텝 없음
- 대부분 LLM으로 작성
- 즉시 복사·배포·재사용 가능
이 글은 그가 축적한 패턴을 “왜 이 방식이 생산적인가” 관점에서 정리한 기록이다.
1. HTML Tool이란 무엇인가
Simon Willison이 말하는 HTML tool은 다음을 만족한다.
- 단일
.html파일 - 인라인 JavaScript + CSS
- 브라우저에서 즉시 실행
- 특정 문제를 아주 잘 해결하는 소형 도구
예시:
- SVG → PNG/JPEG 변환기
- PyPI 패키지 릴리스 간 diff 생성기
- Bluesky 스레드 뷰어
이 도구들은 “앱”이라기보다 확장된 클립보드 + 계산기 + 변환기에 가깝다.
2. 핵심 원칙 1: 반드시 단일 파일
가장 중요한 설계 원칙은 단순하다.
HTML, JS, CSS를 하나의 파일에 넣어라.
이 방식의 효과:
- LLM 출력물을 그대로 복사·붙여넣기 가능
- GitHub에 파일 하나 올리면 즉시 배포
- 호스팅/배포 고민 제거
- 도구 자체가 문서 역할
Simon Willison은 이 패턴 때문에 LLM 기반 개발 속도가 극단적으로 빨라진다고 말한다.
3. React를 피하는 이유 (No Build Step)
그는 프롬프트에 항상 이렇게 쓴다.
“No React.”
이유는 기술적 우월성 문제가 아니다.
- JSX → 빌드 필요
- 빌드 → 복잡성 증가
- 복잡성 → 실험 속도 급감
- 복사/재사용 불가
HTML tool의 목적은:
- 구조적 완성도 ❌
- 즉각적인 유용성 ⭕
4. 의존성은 CDN으로만 로드
외부 라이브러리가 필요하면:
- cdnjs
- jsDelivr
- Skypack
원칙:
- 패키지 버전 고정
- 빌드 없이
<script src=...>로 로드
이 접근의 장점:
- npm / lockfile / 번들링 제거
- 도구 하나가 완결된 산출물
5. LLM으로 시작할 때: Canvas / Artifacts
HTML tool의 시작점은 거의 항상 LLM이다.
- ChatGPT / Gemini → Canvas
- Claude → Artifacts
예시 프롬프트:
Build a canvas that lets me paste JSON and converts it to YAML. No React.
중요 포인트:
- 반드시 “No React” 명시
- 결과물이 바로 실행되는 HTML인지 확인
6. 복잡해지면 Coding Agent로 전환
단일 대화형 LLM → 한계가 있다.
그래서 Simon은:
- Claude Code
- Codex CLI
같은 코딩 에이전트로 전환한다.
장점:
- 실제 실행/테스트 가능
- Playwright 등으로 자동 검증
- 기존 도구 리포지토리에 PR로 직접 반영
HTML tool이 커져도:
- 여전히 단일 파일
- 여전히 빌드 없음
7. 복사 & 붙여넣기를 핵심 UX로 설계
HTML tool의 입출력은 대부분 Clipboard다.
패턴:
- 붙여넣기 → 변환 → 다시 복사
특히 중요한 포인트:
-
클립보드는 여러 포맷을 동시에 보유
- text/plain
- text/html
- 이미지
- 파일
이를 활용한 도구 예:
- HTML 추출기
- 이미지 alt-text 추출기
- 스레드 요약기
8. 디버깅 도구를 먼저 만들어라
Simon의 핵심 노하우 중 하나:
“가능성을 알려면 디버깅 도구부터 만들어라.”
대표 예:
- clipboard-viewer
→ 클립보드에 실제로 어떤 데이터가 들어있는지 시각화
이런 도구들이:
- 이후 수십 개 도구의 기반 지식이 된다.
9. 상태는 URL과 localStorage에 저장
서버가 없어도 상태 저장은 가능하다.
URL에 저장
- 북마크 가능
- 공유 가능
- 짧은 상태에 적합
localStorage
- 큰 상태
- API 키
- 개인 데이터
특히:
- API Key를 서버에 두지 않는다
- 사용자 브라우저에만 저장
10. CORS-enabled API를 수집하라
HTML tool의 진짜 확장력은 CORS 허용 API에서 나온다.
자주 쓰는 API:
- GitHub (raw.githubusercontent.com)
- PyPI
- iNaturalist
- Bluesky
- Mastodon
- GitHub Gist
이 덕분에:
- 서버 없이
- 인증 없이
- 브라우저에서 직접 데이터 활용 가능
11. LLM API도 브라우저에서 직접 호출 가능
- OpenAI
- Anthropic
- Gemini
모두 CORS 지원 JSON API 제공.
패턴:
- API Key를 prompt()로 입력
- localStorage에 저장
- 브라우저에서 직접 호출
UX는 나쁘지만:
- 서버 비용 0
- 배포 부담 0
- 실험 속도 극대화
12. 파일을 “업로드”하지 않아도 된다
<input type="file"> 만으로:
- 이미지
- 비디오
를 브라우저 메모리에서 직접 처리 가능.
예:
- PDF OCR
- 이미지 크롭
- 비디오 ffmpeg 명령 생성기
13. 다운로드도 서버 없이 가능
브라우저에서 생성한 결과물은:
- PNG
- JPEG
- ZIP
- ICS (캘린더)
등으로 즉시 다운로드 가능하다.
HTML tool =
입력 → 계산 → 출력 파일 생성기
14. Pyodide와 WebAssembly의 확장성
Pyodide:
- Python + WebAssembly
- Pandas, NumPy 실행 가능
- PyPI 패키지 로드 가능
WebAssembly:
- OCR 엔진
- SLOC 카운터
- 이미지 압축기
→ 브라우저가 사실상 로컬 런타임
15. 기존 도구를 계속 Remix하라
Simon이 150개 도구를 만든 비결:
이전 도구들이 다음 도구의 설명서다.
LLM에게:
- “이 도구를 참고해서 새 도구 만들어”
- “이 패턴 재사용해”
라고 말할 수 있다.
이때:
- 단일 파일 구조
- 명확한 기능
- 작은 코드베이스
가 결정적인 강점이 된다.
16. 프롬프트와 트랜스크립트를 반드시 기록
Simon은:
- LLM 대화 링크
- Claude Code / Codex CLI 로그
를 항상 커밋 메시지에 남긴다.
이유:
- 재현성
- 학습
- 개선
HTML tool은 결과물만이 아니라 과정도 자산이다.
결론
이 글의 핵심은 기술 스택이 아니다.
- React vs Vanilla ❌
- 프레임워크 ❌
- 최신 아키텍처 ❌
핵심은 이것이다.
“작고, 즉시 쓸 수 있고,
복사 가능한 도구를
얼마나 빠르게 만들 수 있는가”
HTML tools는:
- LLM 시대에 가장 비용 대비 효율이 높은 생산성 단위
- 개인 개발자의 사고력을 그대로 코드로 옮기는 방식
- 서버·빌드·운영을 제거한 순수한 문제 해결 도구
이 패턴은:
- 프론트엔드
- 데이터 엔지니어링
- AI 실험
- 내부 도구
모든 영역에 그대로 적용된다.
