Next.js 기반 관리자 시스템의 Vite 전환 및 구조 개선

한눈에 보기

기존 관리자 시스템은 Next.js를 사용하고 있었지만 서버 렌더링, SEO, API Routes 등 프레임워크의 주요 기능을 활용하지 않았습니다. 반면 클라이언트 중심 구조와 높은 UI 라이브러리 의존성으로 빌드가 느렸고, 화면·상태·API 요청 책임이 섞여 있어 기능 변경 범위가 넓었습니다.

관리자 시스템의 실제 요구사항을 다시 검토한 뒤 Vite, React 19, TanStack Router 기반으로 구조를 재설계했습니다. 목표는 새로운 기술을 도입하는 것이 아니라 기능을 수정할 때마다 기다려야 하는 개발 피드백 시간을 줄이고, 변경 범위를 예측할 수 있게 만드는 것이었습니다.

담당 범위

• 기존 프론트엔드 구조와 빌드 병목 분석
• 기술 스택 검토와 전환 방향 결정
• 라우팅과 접근 권한 구조 설계
• API와 서버 상태 계층 정리
• 공통 레이아웃, 테이블, 필터, 폼 패턴 설계
• 일부 도메인 순수 함수의 단위 테스트 작성
• 운영 흐름과 도메인 규칙 문서화

문제 상황

기존 프로젝트에서는 인증, 권한, 전역 상태, 초기 렌더링, API 호출 책임이 레이어별로 명확하게 분리되지 않았습니다.

• 화면 컴포넌트가 상태와 데이터 요청 책임을 함께 가짐
• 기능 수정 시 여러 영역을 함께 변경해야 함
• 공통 UI 패턴이 화면별로 반복됨
• 무거운 의존성과 기존 빌드 구조로 빌드에 약 10분 소요
• 기능이 늘어날수록 개발 피드백 루프가 느려짐

문제는 단순한 빌드 도구의 속도뿐 아니라, 각 기능의 책임과 변경 경계가 명확하지 않다는 점이었습니다.

판단

이 시스템은 외부 사용자를 위한 콘텐츠 서비스가 아니라 내부 운영자가 사용하는 관리자 시스템이었습니다.

따라서 다음 기준을 우선했습니다.

• SEO와 서버 렌더링보다 빠른 개발 피드백이 중요함
• 라우팅과 접근 권한 흐름을 명시적으로 관리해야 함
• 도메인별 데이터 요청과 상태 책임을 분리해야 함
• 반복되는 관리자 UI를 일관된 방식으로 구현해야 함

기존 Next.js 구조를 유지하며 부분적으로 개선하는 방식과 Vite 기반으로 재구성하는 방식을 검토했고, 현재 시스템이 Next.js의 핵심 기능을 활용하지 않는다는 점을 고려해 Vite 전환을 선택했습니다.

구현

빌드와 라우팅 체계 전환

Vite, React 19, TanStack Router 기반으로 애플리케이션을 재구성했습니다.

TanStack Router의 beforeLoad를 이용해 인증과 권한을 확인하는 레이아웃을 정의하고, 각 화면 내부에 흩어져 있던 접근 제어 분기를 라우팅 계층으로 이동했습니다.

데이터 계층 정리

도메인과 기능을 기준으로 타입, 서비스, 훅, 애플리케이션 책임을 분리했습니다.

• 공통 Axios 인스턴스
• 전역 오류 처리
• TanStack Query 캐시 정책
• 도메인 타입과 API 서비스
• 화면에서 사용하는 데이터 훅

화면 컴포넌트가 API 세부 구현을 직접 알지 않도록 경계를 정리했습니다.

반복 UI 패턴 표준화

관리자 시스템에서 반복적으로 사용하는 테이블, 필터, 폼 구성을 공통 훅과 컴포넌트로 설계했습니다.

공용 컴포넌트는 Storybook에서 상태와 사용 방식을 확인할 수 있도록 구성했으며, 일부 도메인 기능의 순수 함수에는 Vitest 기반 단위 테스트를 작성했습니다.

운영 흐름을 반영한 기능 개선

운영 담당자의 실제 업무 흐름을 파악한 뒤 다음과 같은 기능을 구현하거나 개선했습니다.

• 드래그 앤 드롭
• 테이블 표시 항목 조정
• SMS 재발송
• 문의 답변 템플릿

기술 구조만 변경하는 데 그치지 않고 운영 과정에서 반복되는 작업을 줄이는 방향을 함께 고려했습니다.

결과

• 빌드 시간을 약 10분에서 약 30초로 단축 (측정 환경 기준)
• 개발 피드백 속도 약 95% 개선
• 기능 추가와 수정 시 변경해야 하는 계층이 더 명확해짐
• 공통 UI와 데이터 요청 규칙을 일관되게 적용할 기반 마련
• 프로젝트를 진행하며 파악한 운영 흐름과 도메인 지식을 문서화

회고

이번 작업에서는 최신 기술을 사용하는 것보다 관리자 시스템이 실제로 필요로 하는 조건을 구분하는 과정이 더 중요했습니다.

빌드 도구를 교체하는 것만으로는 유지보수 문제가 해결되지 않기 때문에, 라우팅, 권한, 데이터 요청, 공통 UI의 책임을 함께 재설계했습니다. 이후 구조 개선을 설명할 때는 기술 이름보다 어떤 변경 경계를 만들었고 실제 수정 범위가 어떻게 달라졌는지를 더 구체적으로 기록할 계획입니다.