프런트엔드 프레임워크가 무거워지는 흐름에 지친 백엔드 개발자들 사이에서 htmx가 조용히 세를 넓혀 왔다. htmx의 매력은 단순하다. HTML 속성만으로 "이 버튼이 클릭되면 /clicked로 POST 요청을 보내고, 응답으로 받은 HTML을 특정 요소에 끼워 넣어라"라고 선언적으로 지시할 수 있다. 자바스크립트를 한 줄도 쓰지 않고도, 서버가 HTML 조각만 내려줄 수 있다면 꽤 완성도 높은 애플리케이션을 만들 수 있다. zserge는 인기 프레임워크의 축소판을 직접 만들어 보는 연작의 일환으로, 이 htmx를 밑바닥부터 재구현하며 그 내부 동작을 뜯어봤다. 결론부터 말하면, htmx의 핵심은 놀라울 만큼 작았다.
40줄로 재현되는 핵심 루프
저자가 정리한 htmx의 본질은 세 단계로 요약된다. 화면을 훑어(scan) 어떤 요소가 어떤 이벤트에 반응해야 하는지 파악하고, 트리거가 발생하면 요청을 보내고(send), 돌아온 응답을 목표 요소에 끼워 넣는(swap) 것이다. 그는 이 흐름을 'SSS(scan + send + swap)'라고 이름 붙였다. 실제로 버튼 클릭 시 fetch로 URL을 호출하고 응답 텍스트를 요소에 넣는 최소 동작은 10줄이면 충분했다. 여기에 응답을 HTML로 안전하게 처리하는 처리, 내용을 넣을 대상 요소를 지정하는 x-target, 교체·추가·앞쪽 삽입·삭제 등 삽입 방식을 고르는 x-swap을 더하면, 모든 HTTP 메서드와 다양한 대상·삽입 전략을 지원하는 htmx 클론이 약 40줄로 완성된다. 매번 전체 DOM을 다시 훑는 대신 새로 추가된 내용만 스캔하도록 하는 작은 최적화도 함께 소개됐다.
트리거와 대상 지정의 확장
실무에서 쓸 만하려면 트리거 표현이 풍부해야 한다. 저자는 쉼표로 구분한 이벤트 목록에 지연(delay), 값이 바뀌었을 때만 반응하는 changed, 한 번만 실행하는 once 같은 수식어를 붙이는 문법을 도입했다. 예컨대 x-trigger에 로드 시 실행, 특정 요소 클릭, 500밀리초 지연 후 변경 감지 같은 조합을 한 줄로 표현할 수 있다. load는 사실상 즉시 실행되는 타이머로, changed는 이전 값을 캐싱해 변화가 없으면 요청을 건너뛰는 식으로 각각 특수 처리된다. 대상 지정 역시 단순 querySelector를 넘어 'closest .container'처럼 가장 가까운 조상 요소를, 'next'처럼 다음 형제 요소를 가리킬 수 있도록 확장했는데, 이는 실제 htmx가 취하는 방식과 대체로 같다.
이벤트 기반 플러그인이라는 설계 선택
이 재구현에서 가장 주목할 부분은 확장 구조다. htmx가 htmx:beforeRequest 같은 커스텀 이벤트를 발생시켜 개발자가 요청 흐름에 개입하도록 열어 둔 것처럼, 저자도 beforeRequest·afterRequest·beforeSwap·afterSwap 네 가지 이벤트를 요청을 유발한 요소에서 발생시켰다. 각 이벤트는 현재 요청의 전체 맥락을 담고 있고 preventDefault로 취소할 수 있으며, 앞 이벤트의 세부 정보가 뒤 이벤트로 전달되기 때문에 핸들러가 대상이나 삽입 방식을 도중에 바꿀 수도 있다. 서버가 내려주는 HX-Trigger 헤더로 커스텀 이벤트를 쏘거나 HX-Redirect로 브라우저를 이동시키는 서버 주도 동작도 같은 방식으로 지원된다.
이 설계의 실익은 핵심 루프를 건드리지 않고도 기능을 얹을 수 있다는 데 있다. 대표적으로 링크와 폼을 AJAX로 바꿔 전체 페이지 새로고침을 피하는 '부스팅'은 별도 플러그인조차 필요 없이 짧은 스니펫으로 처리된다. 저자는 이런 확장들이 각각 열 줄 남짓이라 이해하고 디버깅하기 쉬웠으며, 이벤트 기반 플러그인 구조와 SSS API가 기대 이상으로 잘 맞아떨어졌다고 평가한다. 한국의 실무자에게 이 대목이 주는 시사점은 분명하다. 작은 핵심에 확장점을 잘 뚫어 두는 편이, 처음부터 모든 기능을 코어에 욱여넣는 것보다 유지보수에 유리하다는 오래된 원칙을 htmx가 실증하고 있다는 점이다.
축소판이 감춘 것들
다만 저자 스스로 이 결과물을 '최악의 htmx'라 부르는 데는 이유가 있다. htmx의 실제 레퍼런스에는 hx-on, hx-vals, hx-headers, hx-swap-oob, hx-params, hx-push-url, hx-sse, hx-ext 등 겉보기의 단순함을 넘어서는 속성이 즐비하다. 완전한 호환을 이루려면 실패한 fetch와 2XX가 아닌 응답에 대한 제대로 된 오류 처리, 그에 따른 추가 이벤트, 프로미스 기반의 요청 취소가 필요하다. 비동기 확인 대화상자나 뷰 트랜지션처럼 삽입을 잠시 미뤄야 하는 경우를 위해 플러그인이 resolve 로직을 공유하도록 노출하는 작업도 남는다. 결국 이 실험은 htmx를 대체하려는 것이 아니라, 그 겉면의 마법을 걷어내고 '이벤트가 나면 요청을 보내고 응답을 갈아 끼운다'는 본질을 눈으로 확인시키는 데 목적이 있다. 프레임워크를 도입하기 전에 그 내부가 어떻게 도는지 감을 잡고 싶은 개발자에게, 이런 축소판 재구현은 문서 수십 페이지보다 빠른 이해의 지름길이 된다. 전체 코드는 저자의 깃허브 저장소 x에 공개돼 있다.