Next.js 와 Astro 를 같은 회사에서 같이 쓴다

"스택을 통일하라"는 원칙이 틀린 이유는 없다. 우리가 깬 이유는 따로 있다

"프레임워크는 하나로 통일해야 한다"는 말은 반박하기 어렵다. 학습 비용, 코드 공유, 온보딩 속도, 팀 내 일관성. 특히 팀이 작을수록 이 원칙의 압박은 더 강해진다. HEDVION은 결제, 정산, 자동화를 직접 운영하는 작은 팀이다. 엔지니어 한 명이 두 개 이상의 서비스를 맡는 것이 기본이고, 새로운 도구를 추가한다는 건 그 도구의 문서화·유지보수·장애 대응까지 같은 사람이 짊어진다는 뜻이다.

그럼에도 우리는 Next.js와 Astro를 같은 팀에서 함께 쓰기로 결정했다. 이 글은 그 결정이 어떤 맥락에서 나왔는지, 실제로 어떻게 돌아가고 있는지, 그리고 "하나만 쓰는" 대안을 고수했을 때 어떤 비용이 발생했을지를 정직하게 기록한 것이다. 프레임워크 취향의 이야기가 아니라, 배포 리스크와 운영 안정성의 이야기다.

결제·정산 팀에게 "정적 콘텐츠"는 생각보다 훨씬 많다

우리 서비스의 핵심은 인증이 필요한 정산 대시보드, 외부 연동 API, 자동화 파이프라인이다. 이것들은 명확히 서버 사이드 로직이 필요하고, Next.js가 적합하다. 문제는 그 주변에 붙은 콘텐츠 레이어였다.

정산 API 연동 가이드, 수수료 정책 문서, 개발자 FAQ, 파트너사 온보딩 안내. 이것들은 자주 바뀌지 않지만, 실제로 외부 파트너나 내부 운영팀이 가장 많이 들여다보는 페이지다. 그리고 이 페이지들을 Next.js 앱 안에 넣어두면 콘텐츠 하나를 고칠 때마다 서버 사이드 로직이 포함된 전체 앱을 다시 빌드하고 배포해야 한다. 실제로 우리가 겪은 일이다. 수수료율 안내 문서에서 오탈자 하나를 수정했는데, 그 변경이 메인 Next.js 앱의 배포 파이프라인을 탔다. 빌드 약 4분, 배포 후 헬스체크, Slack 알림. 문서 오탈자 수정 하나에 엔지니어의 컨텍스트 스위치가 두 번 이상 발생했고, 결제 앱 배포와 동일한 위험 등급으로 처리됐다.

숫자로 본 역할 분리 — 빌드 시간 87%, JS 96%

Astro로 문서 레이어를 분리한 이후 실측한 수치다. 수치를 먼저 보여주는 이유는, 이 결정이 "Astro가 멋있어서"가 아니라 명확한 비용 차이에서 나왔음을 보여주기 위해서다.

빌드 시간: 문서 콘텐츠 업데이트 기준, Next.js 전체 파이프라인 평균 3분 50초 → Astro 단독 빌드 평균 28초. 동일한 콘텐츠 변경에서 약 87% 단축이다. 하루 3번 문서를 업데이트한다면 파이프라인 대기 시간만 하루 20분 이상 차이가 난다.

클라이언트 JavaScript 페이로드: Next.js로 렌더링하던 문서 페이지의 평균 JS 페이로드 약 312KB(gzip 기준) → Astro 이후 평균 4KB 미만(인터랙티브 컴포넌트 없는 페이지 기준). 약 96% 감소다. 모바일 환경에서 파트너사 실무자들이 접근하는 경우가 많아, 이 차이는 실제 UX와 Core Web Vitals에 영향을 준다.

배포 빈도와 리스크 분리: Next.js 결제 앱 배포는 주 1~2회, 배포 전 스테이징 검증 필수. Astro 문서 사이트는 PR merge 즉시 자동 배포, 스테이징 불필요. 결제 앱의 배포 리스크를 문서 업데이트가 더 이상 공유하지 않는다. 이 분리가 핵심이다.

지금 HEDVION의 역할 기준 — 선택의 로직

현재 우리 팀이 프레임워크를 고르는 기준은 단순하게 수렴됐다.

Next.js: 사용자 인증이 필요한 모든 것. 정산 대시보드, 결제 내역 조회, 자동화 설정 UI, API 연결이 필요한 인터랙티브 화면. 서버 컴포넌트로 민감한 비즈니스 로직을 클라이언트에 노출하지 않아야 하는 페이지 전부다.

Astro: 인증 없이 읽히는 모든 것. 개발자 문서, 정책 페이지, 마케팅 랜딩, 블로그. 콘텐츠 작성자 혹은 운영팀이 엔지니어 없이 직접 수정할 수 있어야 하는 것들이다. 여기에 하나를 더 추가한 기준이 있다. 보안 표면적(attack surface)이다. Astro는 기본적으로 JavaScript를 클라이언트에 거의 전달하지 않는다. 결제 서비스 옆에 붙은 마케팅 페이지에 불필요한 JS가 실행되는 것을 제거하는 것은 사소한 선택이 아니다. XSS 공격 경로 자체가 줄어드는 구조적 이점이다.

함께 쓸 때 실제로 생긴 문제들 — 솔직한 트레이드오프

두 프레임워크 병행이 완전히 무고통이었다면 이 섹션이 필요 없다.

가장 큰 실수는 라우팅 설계였다. /docs 경로를 Next.js 앱 안에 먼저 만들었다가, Astro로 분리하면서 docs.hedvion.com 서브도메인으로 이전했다. SEO 리다이렉트 처리, 기존 링크 깨짐, 파트너사 북마크 만료까지 처리하는 데 약 1주일이 소요됐다. 처음부터 서브도메인으로 분리했다면 발생하지 않았을 비용이다. 두 프레임워크를 함께 쓰기로 결정했다면, URL 구조와 도메인 경계부터 설계하는 것이 선행돼야 한다.

디자인 토큰 동기화는 CSS 커스텀 프로퍼티로 해결했다. design-tokens.css 파일 하나를 두 저장소에서 동일하게 참조한다. Tailwind를 사용하는 팀이라면 tailwind.config.js를 npm 패키지로 분리해 양쪽에서 설치하는 방식이 현실적이다. 학습 비용은 예상보다 낮았다. Astro 문서 사이트 작업의 70% 이상이 마크다운 편집과 레이아웃 수정이다. Next.js에 익숙한 엔지니어가 Astro에 적응하는 데 약 이틀이 걸렸고, Astro에서 React 컴포넌트를 Island 방식으로 내장하는 경우 기존 React 지식이 그대로 활용된다.

모노레포 vs 별도 저장소는 우리는 별도 저장소를 선택했다. 배포 파이프라인의 독립성이 최우선이었기 때문이다. 공유 패키지가 많아진다면 모노레포가 유리할 수 있다. 단, 그 경우에도 배포 파이프라인은 반드시 분리해야 한다.

지금 당장 써먹을 수 있는 실행 시사점

이 글을 읽고 "당장 Astro 도입"으로 결론을 내리는 것은 이르다. 먼저 세 가지 질문에 답해보자.

① 지금 배포 파이프라인에서 콘텐츠 변경이 얼마나 많은가? 지난 한 달의 PR을 돌아봤을 때 코드 변경 없이 텍스트·이미지·문서만 수정한 PR이 전체의 20% 이상이라면, 분리를 검토할 근거가 있다.

② 콘텐츠 배포가 핵심 서비스 배포 리스크를 공유하고 있는가? 마케팅 페이지 배포와 결제 앱 배포가 같은 파이프라인을 탄다면, 그 자체가 비정상적인 리스크 구조다. 결제 앱의 배포 빈도를 줄이고 싶다면 가장 먼저 해야 할 일이 콘텐츠 레이어 분리다.

③ 당장 Astro를 도입하지 않더라도 할 수 있는 것: Next.js의 output: 'export' 정적 내보내기 옵션으로 콘텐츠성 라우트를 먼저 분리해본다. Vercel이나 Netlify에서 문서용 브랜치를 별도 프로젝트로 배포 설정한다. 문서와 앱 저장소를 분리하고 공유 디자인 토큰만 패키지로 추출하는 것부터 시작해도 된다. Astro 도입 여부는 그 다음이다.

프레임워크 선택은 기술 취향의 문제가 아니다. 배포 빈도, 리스크 범위, 팀 역할의 경계를 어떻게 설계할 것인가의 문제다. HEDVION에서 Next.js와 Astro를 함께 쓰는 것은 그 설계의 결과물이다. 그리고 결제·정산 서비스를 운영하는 팀이라면, 이 설계 선택이 단순한 개발자 경험의 문제가 아니라 서비스 안정성과 직결된다는 것을 우리는 실제로 배웠다.