소스, 빌드, 배포의 개념
레시피, 요리, 그리고 완성된 접시 —
내 노트가 사라졌던 하루
소스 · 빌드 · 배포, 오늘에서야 손에 잡힌 개념들
오늘은 사고 하나를 수습하다가, 그동안 어렴풋하게만 알고 있던 개념들이 머릿속에서 확 정리되는 경험을 했다. 새솔CRM의 내 노트(my-notes) 기능을 손보다가 상담일지 탭이 통째로 사라지는 사고가 났는데, 그걸 복구하고 원인을 파고드는 과정에서 “소스”, “빌드”, “배포” 같은 단어들이 실제로 무슨 뜻인지 처음으로 제대로 이해하게 됐다. 비개발자로서 vibe coding을 해온 지 6개월이 넘었는데, 이 개념들을 이제야 손에 잡히게 정리한 게 신기하기도 하고 조금 부끄럽기도 해서 기록으로 남겨둔다.
사건의 시작 — 상담일지가 사라졌다
보안 취약점 알림(Dependabot)이 떠서 uuid라는 아주 작은 패키지를 13버전에서 14버전으로 올렸다.
ID 하나 만들어주는 단순한 부품이라 별생각 없이 승인하고, 서버에서 새로 빌드해서 배포까지 마쳤다.
그런데 브라우저를 열어보니 내 노트 화면이 몇 달 전 옛날 UI로 돌아가 있었고, 상담일지 탭 자체가 없어져 있었다.
개념 하나 — 소스, 빌드, 배포는 서로 다른 것
지금까지는 “코딩하고 → 서버에 올리면 끝”이라고 막연히 생각했다. 그런데 실제로는 그 사이에 빌드(build)라는 중간 과정이 하나 더 있었다.
소스를 고쳐도 다시 빌드하지 않으면 배포본은 안 바뀐다. 반대로 배포본(dist)에 직접 손을 대서 뭔가를 끼워 넣어도, 소스에는 그 내용이 없으면 다음에 처음부터 다시 빌드할 때 그 부분은 감쪽같이 사라진다. 이번 사고가 정확히 이 패턴이었다.
진짜 원인 — 편법으로 얹혀 있던 상담일지
Git 히스토리를 뒤져보니 원인이 나왔다.
my-notes/src)가 아니라 이미 빌드되어 배포된 index.html에만 스크립트를 손으로 끼워 넣는 방식으로 구현됨. 리액트 컴포넌트로 정식 구현하는 대신, 완성된 HTML에 스크립트 하나 얹는 빠른 길을 택한 것으로 보인다.npm run build를 다시 실행. Vite가 “소스에 있는 그대로” 배포본을 처음부터 새로 만들어버림. 소스에는 상담일지가 없었으니, 새 배포본에도 당연히 없었다.“배포 결과물에만 존재하고 정식 소스에는 없는 기능”은, 언제든 재빌드가 일어나는 순간 사라질 운명이었다. 문제는 uuid가 아니라, 애초에 편법으로 저장된 구조였다.
개념 둘 — 브라우저는 자바스크립트만 읽는다
브라우저가 직접 실행할 수 있는 언어는 사실상 자바스크립트(JavaScript)뿐이다. 크롬이든 사파리든, 브라우저 안에는 자바스크립트 엔진만 내장되어 있어서 파이썬이나 자바 코드를 그대로 줄 수는 없다.
그렇다고 파이썬·자바·PHP가 웹에서 쓸모없는 건 아니다. 이 언어들은 서버(백엔드) 쪽에서 자유롭게 쓰인다. 워드프레스가 PHP로 만들어진 것도 이런 이유 — 서버에서 PHP가 화면용 HTML을 만들어서 브라우저로 보내주는 것이다.
프론트엔드 (브라우저)
- 사실상 JavaScript만 직접 실행 가능
- React·Vue도 결국 빌드를 거쳐 JS로 변환
- 화면, 클릭, 상호작용을 담당
백엔드 (서버)
- 언어 제약 없음 — JS, Python, Java, PHP 등 자유
- 데이터 처리, 로그인, 계산 담당
- 화면을 만들어 브라우저로 보내주는 역할
개념 셋 — Node.js, Express, SQLite의 역할 차이
새솔CRM을 만들면서 매일 쓰는 단어들인데도 정확히 뭐가 뭔지 헷갈렸던 세 가지를 이번에 확실히 구분했다.
새솔CRM처럼 많지않은 수임처를 관리하는 1인 개발 프로젝트에는, 무겁고 별도 관리가 필요한 DB보다 SQLite처럼 가벼운 조합이 오히려 더 잘 맞았다.
리액트는 언제 쓰고, 순수 HTML은 언제 쓰나
핵심은 화면이 얼마나 복잡하고 동적으로 움직여야 하느냐다.
React가 필요한 경우
- 데이터가 실시간으로 계속 바뀜 (예: 내 노트)
- 탭 전환·필터링·검색 등 상호작용이 많음
- 여러 화면 상태가 서로 얽혀있음
순수 HTML/JS로 충분한 경우
- 입력 → 계산 → 결과, 단순한 흐름 (예: 양도세 계산기)
- 빌드 과정 자체가 불필요
- 더 가볍고 배포도 간단함
재발 방지 — 편법을 정식 소스로 옮기다
원인을 알았으니 해법은 명확했다. 배포본에만 얹혀 있던 상담일지·노트포맷 스크립트를, 정식 소스 쪽으로 편입시키는 것.
my-notes/public/로 이동 — Vite가 이 폴더 내용을 매 빌드마다 자동으로 결과물에 복사해준다.index.html에 스크립트 태그와 커스텀 스타일을 직접 추가 — 빌드가 이 템플릿을 기준으로 결과물을 만들기 때문에, 이후로는 몇 번을 다시 빌드해도 자동 포함된다.이제 my-notes에 어떤 패키지 업그레이드나 다른 작업을 하더라도, 상담일지가 갑자기 사라지는 사고는 구조적으로 다시 일어날 수 없다.
오늘의 정리
- 소스(레시피) → 빌드(요리) → 배포본 dist(완성 요리). 소스에 없는 걸 배포본에만 얹으면 재빌드할 때 사라진다.
- 브라우저는 자바스크립트만 직접 실행한다. React도 결국 빌드를 거쳐 자바스크립트가 된다.
- Node.js는 엔진, Express는 운전대, SQLite는 서랍장 — 각자 역할이 다르다.
- 화면이 단순하면 순수 HTML/JS, 복잡하고 동적이면 React.
- 백엔드는 언어 제약이 없다. Node.js든 Python이든 상황에 맞게 섞어 써도 된다.
사고는 아팠지만, 그 덕에 그동안 어렴풋했던 개념들을 확실히 잡을 수 있었으니 남는 장사였다고 해두고 싶다.
— 새솔CRM 개발일지, 2026.07.22