바이브코딩 웹앱 1편 - GitHub Pages에 올리는 법
개인 웹앱을 만들 때 처음 막히는 지점은 코드보다 “이걸 어디에 올리지?”다. 화면만 보여 주는 홈페이지라면 서버를 먼저 마련할 필요가 없다. 세븐핑거스가 운영 중인 sfs_apps도 React·TypeScript·Vite로 만든 프런트를 정적 파일로 빌드하고, GitHub Pages에 따로 올리는 구조다. 저장소를 고치면 화면 파일을 다시 만들고, 배포용 브랜치에는 그 결과물만 남긴다.
정적 홈페이지가 맡는 일
정적 사이트는 방문자가 페이지를 열 때 HTML, CSS, JavaScript와 이미지를 받아 브라우저에서 화면을 만든다. 소개 페이지, 글 목록, 계산기처럼 브라우저 안에서 처리할 수 있는 기능은 이 방식으로 충분하다. GitHub Pages는 이런 정적 파일을 저장소에서 게시하는 서비스라서, 개인 프로젝트의 첫 화면을 올리기에 잘 맞는다.
sfs_apps의 프런트는 Vite가 만든 결과물인 dist 폴더를 gh-pages 브랜치에 올린다. 소스 브랜치와 공개 파일을 분리해 두면 개발 중인 설정 파일이나 작업 흔적이 사용자에게 노출되지 않는다. GitHub Pages는 저장소의 특정 브랜치와 폴더를 게시 원본으로 지정할 수 있다. 프로젝트 사이트 주소는 저장소 이름이 경로에 포함될 수 있으므로, Vite의 base 값도 그 경로와 맞춰야 이미지·스크립트가 깨지지 않는다.
먼저 나눌 것은 화면과 비밀값이다
정적 프런트에 넣어도 되는 것은 화면 구성, 공개 이미지, 공개 API 주소다. 반대로 API 키, 서비스 계정 JSON, 결제 비밀키처럼 노출되면 안 되는 값은 넣으면 안 된다. Vite의 VITE_ 환경 변수는 빌드된 브라우저 코드에 포함될 수 있다. 그래서 sfs_apps의 운영용 프런트에는 Worker API 주소만 두고, 실제 비밀값은 다음 편에서 다룰 Cloudflare Worker 쪽에 둔다.
처음부터 기능을 크게 잡으면 배포가 복잡해진다. 홈 화면과 입력 폼, 결과를 보여 주는 화면처럼 브라우저만으로 확인 가능한 흐름부터 GitHub Pages에 올려 보는 편이 좋다. 실제 프로젝트에서도 frontend와 workers 폴더를 나눠 두니, 화면 변경과 API 변경을 따로 빌드·배포할 수 있었다.
무료 티어라는 말의 범위
GitHub Pages는 정적 파일 게시에 적합하지만, 모든 비용이 자동으로 0원이 된다는 뜻은 아니다. 개인 도메인, 외부 유료 API, 대용량 트래픽은 각각의 정책과 사용량에 따라 달라진다. 시작 전에는 GitHub Pages의 현재 사용 조건과 제한을 확인하고, 공개 저장소인지 비공개 저장소인지에 따른 플랜 조건도 살펴야 한다. 그래도 화면을 빠르게 공개하고 주소로 열어 보는 첫 단계는 상당히 가벼워진다.
운영자 실전 노트
세븐핑거스(Seven Fingers Studio)는 sfs_apps에서 Vite의 배포 경로를 저장소 이름과 맞추고, 정적 프런트를 GitHub Pages로 분리했다. 이 설정을 빼먹으면 로컬에서는 보이던 이미지와 JavaScript가 공개 주소에서 404가 나는 경우가 있다. 배포 전에 개발자 도구의 네트워크 탭에서 정적 파일 주소가 예상한 경로로 요청되는지 확인해 두면 원인을 빨리 찾는다.
FAQ
Q. GitHub Pages만으로 로그인이나 저장 기능도 만들 수 있나요?
화면은 만들 수 있지만, 비밀값을 숨기거나 사용자 데이터를 안전하게 처리할 서버 역할은 별도로 필요하다. 다음 편의 Worker처럼 API를 분리하는 이유다.
Q. Vite의 base 값은 언제 필요한가요?
사용자명.github.io/저장소이름/ 형태의 프로젝트 사이트라면 경로를 맞춰야 한다. 사용자 또는 조직의 루트 사이트처럼 저장소 이름이 주소에 없는 경우에는 설정이 달라질 수 있다.