📖 Nuxt 4를 선택한 이유와 아키텍처 정리

Vue.js로 웹 프로젝트를 하다 보면 자연스럽게 마주하게 되는 벽이 있다. 바로 SEO(검색엔진 최적화)와 초기 로딩 속도 문제다. 클라이언트 사이드 렌더링(CSR) 중심의 SPA 구조에서는 대형 프로젝트나 검색 유입이 중요한 서비스를 만들 때 한계가 명확하다.

이 문제를 해결하기 위해 도입한 Nuxt, 그중에서도 최신 버전인 Nuxt 4를 직접 다루며 파악한 핵심 구조와 생태계 변화, 그리고 실무에서 느낀 점들을 정리해본다.

🔎 기존 Vue 생태계의 갈증과 Nuxt의 등장 배경

초창기 Vue는 화면을 빠르게 그릴 수 있는 훌륭한 UI 라이브러리였다. 하지만 프로젝트를 구성하려면 개발자가 직접 판을 짜야 했다.

• 라우터는 Vue Router, 상태 관리는 Pinia, 메타태그 관리는 별도 패키지...
• 빌드 최적화와 SSR(서버사이드 렌더링)을 직접 구현하려고 하면 Node.js 서버 세팅부터 시작해 복잡도가 급격히 올라간다.

"가장 이상적인 구조를 미리 정의해 둘 테니, 너희는 비즈니스 로직에만 집중해"라는 철학으로 나온 프레임워크가 바로 Nuxt다. 라우팅, 데이터 페칭, 빌드 최적화가 하나의 규격 안에 통합되어 있어 개발 생산성을 극대화해 준다.

🧐 Nuxt 4로 넘어오면서 무엇이 달라졌을까?

최신 Nuxt 4에 이르러서는 프론트엔드와 백엔드의 경계가 더욱 깔끔하게 정돈되었다.

📁 ① 명확해진 단일 앱 레이어 (app/ 디렉토리)

과거에는 루트 경로에 컴포넌트, 페이지, 레이아웃 등이 섞여 있어 프로젝트가 커지면 구조가 산만해졌다. Nuxt 4에서는 모든 프론트엔드 자산이 app/ 폴더 안으로 완벽히 응집된다.

my-nuxt-project/
├── app/                  # 💡 프론트엔드 소스코드 집약 (pages, components 등)
├── server/               # 💡 독립된 백엔드/API 레이어 (Nitro 엔진)
├── nuxt.config.ts
└── package.json

이로 인해 프론트엔드 영역과 서버 영역(server/)의 구분이 명확해져 유지보수할 때 정신 건강에 이롭다.

⚡ ② Nitro 런타임 엔진

Nuxt 하부에서 서버를 지탱하는 Nitro는 개발자가 인프라 환경(Node.js, Vercel, AWS Lambda 등)을 크게 신경 쓰지 않도록 추상화되어 있다.

코드 한 줄 수정 없이 에지(Edge) 환경에 배포할 수 있으며, 캐싱(ISR, SWR) 설정도 설정 파일 몇 줄로 제어할 수 있어 인프라 비용과 성능을 동시에 잡을 수 있다.

🔥 개발하면서 체감하는 Nuxt의 강력한 무기들

• 설정보다 관습 (Convention over Configuration): app/pages/에 파일을 만들면 라우팅이 알아서 잡히고, ref, computed 같은 Vue 핵심 API나 컴포넌트를 일일이 import 할 필요가 없다. (Auto-imports)
• useFetch를 통한 중복 요청 차단 (Payload 직렬화): 서버에서 데이터를 가져온 상태(State)를 그대로 브라우저로 넘겨주기 때문에(Hydration), 클라이언트가 켜졌을 때 똑같은 API를 두 번 부르는 상용구 현상을 원천 차단한다.
• 엔드투엔드 타입 안전성: 백엔드 API 레이어(server/api/)의 응답 구조가 바뀌면, 프론트엔드에서 데이터를 호출하는 코드까지 실시간으로 타입 추론이 연동되어 런타임 에러를 획기적으로 줄여준다.
• 서버 컴포넌트 (*.server.vue): 무거운 라이브러리나 마크다운 파서 등을 오직 서버에서만 렌더링하고 브라우저로는 정적 HTML만 보낸다. 덕분에 클라이언트 번들 사이즈를 방어하기 좋다.

⚠️ 실무에서 Nuxt를 쓸 때 반드시 알아야 할 주의점

막 쓰기에는 편하지만, SPA에만 익숙해져 있다면 몇 가지 삽질 포인트가 있다.

• SSR과 브라우저 전역 객체 (window, localStorage 등): 서버에서 먼저 HTML을 그릴 때는 저런 객체들이 존재하지 않는다. 따라서 렌더링 단계에서 window is not defined 에러를 뿜기 십상이다. 브라우저 API는 반드시 onMounted 훅 내부나 import.meta.client 체크를 거친 뒤에 사용해야 한다.
• 하이드레이션 미스매치 (Hydration Mismatch): 서버에서 그린 HTML 결과물과 브라우저가 처음 실행할 때의 결과물이 미묘하게 다르면 콘솔에 경고창이 가득 찬다. (예: 날짜나 랜덤 값을 그대로 렌더링할 때 발생하기 쉽다.)
• 무분별한 SSR은 금물: 모든 페이지를 다 SSR로 돌릴 필요는 없다. 동적으로 실시간 데이터를 먹일 필요가 없는 페이지는 routeRules를 통해 SSG나 ISR로 빼는 설계적 고민이 필요하다.

🎯 마치며: 프레임워크가 주는 제약 속의 자유

Nuxt는 처음에는 "Vue를 조금 더 편하게 쓰게 해주는 껍데기"처럼 보이지만, 깊게 팔수록 "웹 애플리케이션을 어떤 구조로 설계하고 배포해야 하는지"에 대한 선명한 정답을 제시해주는 프레임워크다.

처음에는 강력한 규격(Convention)이 답답하게 느껴질 수도 있지만, 이 규격이 주는 안정감과 Nitro 엔진이 가져다주는 인프라의 유연함을 경험하고 나면, 중대형 웹 서비스를 혼자서도 뚝딱 만들어낼 수 있는 가장 강력한 무기임을 깨닫게 된다.