React를 버리고 HTMX로 전환하기: 2023년 마이그레이션 가이드

Meta Description: 2023년에 코드베이스에서 React.js를 제거하고 UI 상호작용을 위해 HTMX를 채택함으로써 어떻게 스택을 단순화하고 성능을 높일 수 있는지 알아보세요. 실제 사례를 담은 가이드가 포함되어 있습니다.

요약 (TL;DR)

2023년, 점점 더 많은 개발 팀들이 React.js가 모든 프로젝트에 적합한 도구인지 의문을 갖기 시작했습니다. HTMX는 HTML에서 직접 현대적인 브라우저 기능을 사용할 수 있게 해주는 경량 라이브러리로서 매력적인 대안으로 떠올랐습니다. 이 가이드는 React에서 HTMX로 마이그레이션할 때의 이유(why), 방법(how), 그리고 _주의해야 할 점(what to watch out for)_을 다루며, 오늘 바로 실행할 수 있는 실질적인 단계들을 제공합니다.

핵심 요약 (Key Takeaways)

• HTMX는 모든 프로젝트를 위한 React 대체제가 아닙 — 서버 렌더링(Server-rendered) 중심의 콘텐츠 집약적인 앱에는 뛰어나지만, 상태(State)가 매우 많은 UI에서는 어려움을 겪습니다.
• React를 제거하면 많은 실제 사례에서 JavaScript 번들 크기를 **85-95%**까지 줄일 수 있습니다.
• 마이그레이션은 강력한 서버 측 프레임워크(Django, Rails, Laravel, Go 등)와 결합될 때 가장 효과적입니다.
• HTMX의 학습 곡선(Learning curve)은 React의 생태계보다 현저히 낮습니다.
• 모든 것을 한꺼번에 바꿀 필요는 없습니다 — 전환기 동안 하이브리드(Hybrid) 접근 방식도 유효합니다.
• 성능 향상은 실질적이지만, 아키텍처 측면의 규율(Architectural discipline)이 필요합니다.

2023년에 팀들이 React.js를 제거하기 시작한 이유

React는 대략 2015년부터 프론트엔드 개발을 지배해 왔습니다. 강력하고, 지원이 잘 되며, Meta의 지원을 받습니다. 그런데 왜 2023년의 엔지니어링 팀들은 코드베이스에서 React를 적극적으로 제거하고 있었을까요?

솔직한 답변은 다음과 같습니다: React는 많은 앱이 실제로 겪고 있지 않은 문제들을 해결합니다.

JavaScript 피로도(JavaScript Fatigue) 문제

2023년 기준으로, 전형적인 React 애플리케이션은 다음과 같은 것들을 포함하여 번들링됩니다:

• React + ReactDOM (~130KB minified)
• 상태 관리 라이브러리 (Redux, Zustand, Jotai — 무엇을 선택하든)
• 라우팅 라이브러리 (React Router, TanStack Router)
• 데이터 페칭(Data-fetching) 레이어 (React Query, SWR, Apollo)
• 빌드 도구 (Webpack, Vite, Babel)

콘텐츠 중심의 웹사이트, 마케팅 플랫폼, 또는 전통적인 CRUD 애플리케이션의 경우, 이는 엄청난 양의 복잡성입니다. 여러분은 근본적으로 HTML인 것을 렌더링하기 위해 수백 킬로바이트(KB)의 JavaScript를 전송하고 있는 것입니다.

"상황에 따라 다릅니다" (The "It Depends" Moment)

2023년의 논의는 몇몇 유명한 포스트와 사례 연구들에 의해 촉발되었습니다. 여기에는 자신들의 JavaScript 감소 노력에 관한 널리 인용된 GitHub 블로그 포스트와, Hotwire(HTMX의 개념적 사촌 격인 기술)를 통한 "The HTML Over The Wire" 접근 방식을 강력하게 옹호한 DHH의 발언 등이 포함됩니다.

팀들은 단순하지만 강력한 질문을 던지기 시작했습니다: "우리가 여기서 실제로 클라이언트 사이드 SPA (Single Page Application)가 필요한가?"

많은 이들에게 정직한 답변은 "아니오"였습니다.

[INTERNAL_LINK: SPA vs 서버 렌더링 아키텍처를 사용해야 하는 시점]

HTMX란 무엇이며 왜 중요한가?

HTMX는 Carson Gross가 만든 작은 규모(~14KB minified and gzipped)의 JavaScript 라이브러리입니다. 이 라이브러리의 핵심 철학은 급진적입니다: HTML은 단순히 JavaScript를 위한 렌더링 대상이 아니라, 웹의 하이퍼미디어 (Hypermedia)여야 합니다.

HTMX를 사용하면 다음과 같은 기능을 가능하게 하는 커스텀 속성(attributes)으로 HTML을 확장할 수 있습니다:

• 모든 요소에서의 AJAX 요청 (폼(form)과 링크뿐만 아니라)
• CSS 전환 (Transitions)
• WebSockets 및 서버 전송 이벤트 (Server-Sent Events)
• 전체 페이지 새로고침 없는 부분 페이지 업데이트 (Partial page updates)

다음은 구체적인 예시입니다. React에서 데이터를 가져와 표시하는 간단한 버튼은 다음과 같이 보일 수 있습니다:

function UserCard() {
  const [user, setUser] = useState(null);

...

HTMX에서 동일한 기능은 다음과 같이 보입니다:

<button hx-get="/user/1" hx-target="#user-card" hx-swap="innerHTML">
  Load User
</button>
...

여러분의 서버는 JSON이 아닌 HTML 조각 (fragment)을 반환하며, HTMX는 이를 대상 요소에 삽입합니다. 여러분이 작성한 JavaScript는 없습니다. 상태 관리 (State management)도 없습니다. 빌드 단계 (Build step)도 없습니다.

React vs. HTMX: 정직한 비교

솔직한 결론: 복잡하고 상태 중심적인 (stateful) UI에는 React가 승리합니다. 그 외의 모든 경우에는 HTMX가 승리합니다. 그리고 그 "그 외의 모든 것"은 대부분의 개발자가 인정하는 것보다 훨씬 더 큰 범주입니다.

React를 제거하는 것이 합리적인 경우 (그리고 그렇지 않은 경우)

HTMX 마이그레이션에 적합한 후보

• 마케팅 웹사이트 및 랜딩 페이지 — 클라이언트 상태 (client state)에 따라 콘텐츠가 바뀌는 경우가 거의 없음
• 관리자 대시보드 (Admin dashboards) — 주로 양식 (forms), 테이블, 데이터 표시로 구성됨
• 이커머스 상품 목록 — 필터링된 검색과 함께 서버 사이드 렌더링 (server-rendered)됨
• 블로그 플랫폼 및 CMS 프론트엔드 — 거의 전적으로 서버 주도적 (server-driven)
• 표준 CRUD를 사용하는 SaaS 애플리케이션 — 생성(create), 읽기(read), 수정(update), 삭제(delete) 작업에 SPA (Single Page Application)가 필요하지 않음
• 내부 도구 (Internal tools) — 번들 크기보다 개발자 경험 (developer experience)이 더 중요한 경우

HTMX 마이그레이션에 부적합한 후보

• Figma와 같은 디자인 도구 — 방대한 클라이언트 사이드 상태 (client-side state), 캔버스 조작 필요
• 실시간 협업 에디터 — Google Docs 스타일
• 복잡한 데이터 시각화 대시보드 — D3.js 또는 Recharts가 핵심적인 역할을 수행하는 경우
• 게임 또는 인터랙티브 시뮬레이션
• 오프라인 우선 PWA (Offline-first PWAs) — 클라이언트 사이드 상태가 핵심인 경우

[INTERNAL_LINK: 귀하의 SaaS를 위한 적절한 프론트엔드 아키텍처 선택하기]

단계별 가이드: React에서 HTMX로 마이그레이션하는 방법

1단계: React 컴포넌트 감사 (Audit)

코드를 건드리기 전에, 기존 React 컴포넌트를 복잡도에 따라 분류하세요:

• 단순한 컴포넌트 (정적 렌더링, 최소한의 상태): 가장 먼저 마이그레이션
• 중간 규모 컴포넌트 (하나 또는 두 개의 useState 훅, 기본적인 페칭 (fetching)): 두 번째로 마이그레이션
• 복잡한 컴포넌트 (무거운 상태, 컨텍스트 (context), 서드파티 통합): 마지막에 마이그레이션하거나 React에 그대로 유지

Webpack Bundle Analyzer와 같은 도구를 사용하면 시작하기 전에 무엇이 번들 크기에 기여하고 있는지 정확히 파악하는 데 도움이 됩니다.

2단계: 서버 사이드 프레임워크 선택

HTMX는 서버에 구애받지 않지만(server-agnostic), 서버가 HTML 조각(fragments)을 효율적으로 반환할 수 있을 때 가장 잘 작동합니다. 강력한 조합은 다음과 같습니다:

• Python: django-htmx를 사용하는 Django (환상적이고 관리가 잘 되는 확장 기능)
• Ruby: Hotwire/Turbo를 사용하는 Rails (개념적으로 유사함)
• PHP: Livewire 또는 순수 HTMX를 사용하는 Laravel
• Go: Templ 또는 표준 html/template
• Node.js: EJS 또는 Pug 템플릿을 사용하는 Express
• Java: Thymeleaf를 사용하는 Spring Boot

핵심 요구사항: 서버는 JSON이 아닌 HTML을 반환해야 합니다. 이는 프론트엔드 소비를 위한 REST API를 구축하는 데 익숙한 팀들에게는 사고 모델(mental model)의 전환이 필요합니다.

3단계: HTMX 설정하기

설치는 React 설정과 비교하면 부끄러울 정도로 간단합니다:

<script src="https://unpkg.com/htmx.org@1.9.6"></script>

또는 선호하는 경우 npm을 통해 설치할 수 있습니다:

npm install htmx.org

Babel도, JSX 변환(transform)도, webpack 설정도 필요 없습니다. 그게 전부입니다.

4단계: 컴포넌트를 점진적으로 마이그레이션하기

한꺼번에 모든 것을 바꾸는 빅뱅 마이그레이션(big-bang migration)을 시도하지 마세요. 대신 다음과 같이 진행하세요:

1. 고립된 기능 하나를 식별합니다 — 검색창, 데이터 테이블, 모달 등
2. HTML 조각을 반환하는 서버 엔드포인트(endpoint)를 생성합니다
3. React 컴포넌트를 HTMX 기반의 HTML로 교체합니다
4. 철저하게 테스트합니다, 특히 예외 케이스(로딩 상태, 에러, 빈 상태)를 확인하세요
5. 반복합니다

마이그레이션 기간 동안 HTMX와 React는 동일한 페이지 내에서 공존할 수 있습니다. React 컴포넌트를 서버 사이드에서 렌더링한 다음, 이후의 상호작용은 HTMX가 처리하도록 할 수 있습니다.

5단계: HTMX에서 일반적인 React 패턴 처리하기

로딩 상태 (Loading states):

<button hx-get="/data" hx-indicator="#spinner">
  Load Data
</button>
...

폼 유효성 검사 (Form validation):

<form hx-post="/submit" hx-target="#result" hx-swap="outerHTML">
  <input name="email" type="email" required>
  <button type="submit">Submit</button>
...

업데이트를 위한 폴링 (Polling for updates):

<div hx-get="/notifications" hx-trigger="every 5s" hx-swap="innerHTML">
</div>

6단계: React 의존성 제거하기

모든 컴포넌트의 마이그레이션(Migration)을 완료했다면, 프로젝트에서 React를 제거할 수 있습니다:

npm uninstall react react-dom @types/react @types/react-dom

그 다음, 번들러(Bundler)에서 React 전용 빌드 설정을 제거하세요. 만약 프론트엔드 전체가 이제 HTMX로 구성되어 있다면, JavaScript 빌드 단계가 아예 필요하지 않을 수도 있습니다.

실제 사례: 2023년 팀들이 보고한 결과

2023년에 여러 팀이 자신들의 마이그레이션 과정을 공개적으로 기록했습니다. 공통적인 결과는 다음과 같았습니다:

• 번들 크기 감소 (Bundle size reduction): JavaScript 페이로드(Payload)가 85-95% 더 작아짐
• 상호작용 가능 시간 (Time to Interactive, TTI): 중간 수준의 연결 속도에서 40-60% 개선
• 개발자 온보딩 (Developer onboarding): 신규 개발자가 며칠이 아닌 몇 시간 만에 생산성을 발휘함
• 서버 부하 (Server load): 약간의 증가 (서버가 이제 JSON뿐만 아니라 HTML도 렌더링함), 하지만 HTML 조각(Fragments)의 CDN 캐싱을 통해 상쇄됨
• Lighthouse 점수: 성능(Performance) 및 권장 사항(Best Practices) 카테고리에서 상당한 개선

특히 주목할 만한 사례로, 프로젝트 관리 도구를 운영하는 한 SaaS 팀은 대시보드를 React에서 HTMX + Django로 마이그레이션한 후 JavaScript 번들 크기를 1.2MB에서 67KB로 줄였다고 보고했습니다. 이들의 Lighthouse 성능 점수는 54점에서 91점으로 급등했습니다.

[INTERNAL_LINK: 2024년에 실제로 중요한 웹 성능 지표]

마이그레이션을 지원하는 도구 및 라이브러리

개발용

• VS Code HTMX Extension — HTMX 속성에 대한 인텔리센스(IntelliSense)를 제공하며, 실제로 매우 유용함
• htmx-debugger — HTMX 요청을 디버깅하기 위한 브라우저 확장 프로그램
• 브라우저 개발자 도구 (Browser DevTools) — 솔직히 말해서, HTMX를 사용하면 특화된 도구가 훨씬 적게 필요합니다.

스타일링용 (React 컴포넌트 모델을 버리게 되었으므로)

• Tailwind CSS — 서버에서 렌더링된 HTML 조각과 아름답게 작동하며, 강력히 추천함
• Alpine.js — HTMX가 처리하지 못하는 클라이언트 측 상호작용(드롭다운, 토글 등)을 위한 가벼운 JavaScript 라이브러리이며, HTMX와 잘 어울림

테스트를 위한 도구

• Playwright — React를 사용하든 HTMX를 사용하든 엔드 투 엔드 테스트 (End-to-end testing) 방식은 동일하게 작동합니다.
• Django Test Client / Rails system tests — 서버 측 테스트 (Server-side testing)가 더욱 중요해지며 더욱 직관적으로 변합니다.

흔한 실수와 방지 방법

실수 1: React의 사고 모델을 복제하려고 시도하는 것

HTMX는 다른 방식의 사고를 요구합니다. 클라이언트에서 상태 (State)를 관리하는 것이 아니라, **서버가 진실의 원천 (Source of truth)**입니다. HTMX에서 React 패턴을 재현하려는 개발자들은 어려움을 겪을 것입니다. 서버 중심 (Server-centric) 모델을 받아들이세요.

실수 2: 클라이언트 전용 상태를 위해 Alpine.js를 무시하는 것

일부 UI 상호작용은 진정으로 클라이언트 측에서 이루어집니다: 드롭다운 메뉴, 모달 토글, 탭 전환 등입니다. HTMX는 이러한 작업을 우아하게 처리하지 못합니다. Alpine.js (2KB)는 이 간극을 완벽하게 메워주며, HTMX와 함께 작동하도록 설계되었습니다.

실수 3: CSRF 보호를 잊는 것

HTMX가 POST 요청을 보낼 때 CSRF 토큰이 필요합니다. 대부분의 서버 프레임워크가 이를 처리하지만, HTMX가 토큰을 포함하도록 설정해야 합니다:

document.body.addEventListener('htmx:configRequest', (event) => {
  event.detail.headers['X-CSRFToken'] = getCookie('csrftoken');
});

실수 4: 서버 측 템플릿 복잡성을 과소평가하는 것

서버 측 템플릿이 더 많은 렌더링 로직을 처리하게 됨에 따라 점점 더 복잡해질 것입니다. 견고한 템플릿 시스템과 컴포넌트와 유사한 템플릿 포함/부분 템플릿 (Template includes/partials)에 투자하세요.

솔직한 결론

2023년에 코드베이스에서 React.js를 제거하고 UI 상호작용을 위해 HTMX를 채택한 것은 단순한 트렌드가 아니라 하나의 교정이었습니다. JavaScript 생태계는 기본값으로서 복잡성을 향해 표류해 왔으며, HTMX는 광범위한 웹 애플리케이션 클래스에 대해 정당한 아키텍처적 대안을 제시했습니다.

HTMX가 귀하의 프로젝트에 적합할까요? 스스로에게 솔직하게 물어보세요: "내 애플리케이션의 복잡성이 진정한 UI 요구사항 때문인가, 아니면 내가 선택한 프레임워크 때문인가?"

만약 답이 후자라면, HTMX를 진지하게 고려해 볼 가치가 있습니다.

오늘 바로 마이그레이션을 시작하세요

스택을 단순화할 준비가 되셨나요? 작게 시작해 보세요. 코드베이스에서 React 컴포넌트 하나를 선택하세요. 클라이언트 상태 (client state)가 최소화된 데이터 페칭 (data-fetching) 컴포넌트라면 가장 이상적입니다. 그리고 그것을 HTMX로 다시 구축해 보세요. 이 접근 방식이 귀하의 프로젝트에 적합한지 오후 한나절이면 이해할 수 있을 것입니다.

더 깊이 있는 학습을 원하신다면, HTMX 공식 문서는 정말 훌륭하며 읽기 쉽습니다. Carson Gross가 저술한 _Hypermedia Systems_라는 책(온라인에서 무료로 제공됨)은 HTMX의 개념을 이해할 수 있게 해주는 철학적 토대를 제공합니다.

React에서 HTMX로 마이그레이션해 보셨나요? 아래 댓글로 여러분의 경험을 공유해 주세요.

자주 묻는 질문 (FAQ)

1. HTMX는 본격적인 애플리케이션을 위한 프로덕션 환경(production-ready)에 적합한가요?