gil-wiki/wiki/nuxt-rendering-modes.md

Nuxt 렌더링 모드

카테고리: 핵심 개념 최종 수정: 2026-05-13 관련: nuxt-lifecycle, nuxt-performance, nuxt-data-fetching

요약

Nuxt는 Universal(SSR), CSR, Hybrid, Edge-Side 4가지 렌더링 모드를 지원한다. 기본값은 Universal(SSR) 이며, routeRules로 라우트별로 다른 전략을 섞을 수 있다.

---

1. Universal Rendering (기본값, SSR + Hydration)

서버에서 완전한 HTML을 생성 → 브라우저로 전달 → 클라이언트에서 Vue가 HTML을 "인계받아" 인터랙티브하게 만듦(Hydration).

<!-- server와 client 모두에서 실행 -->
<script setup lang="ts">
const counter = ref(0)  // 서버·클라이언트 양쪽에서 초기화됨

const handleClick = () => {
  counter.value++  // 클라이언트에서만 실행됨
}
</script>

실행 환경 요약:

항목	서버	클라이언트
<script setup> 루트 코드	✅	✅
이벤트 핸들러	❌	✅
onMounted 훅	❌	✅
Middleware / Pages	✅	✅ (hydration 시)
.server 플러그인	✅	❌
.client 플러그인	❌	✅

장점: 빠른 첫 페이지 로드, SEO 최적화, 즉각적인 콘텐츠 표시
단점: 서버 비용, 브라우저/서버 API 차이로 인한 개발 제약

---

2. Client-Side Rendering (CSR, SPA)

// nuxt.config.ts
export default defineNuxtConfig({
  ssr: false,
})

ssr: false로 설정하면 순수 SPA로 동작. 브라우저에서만 렌더링.

💡 경험: ssr: false + nuxt generate 조합 시 spa-loading-template.html 파일로 로딩 화면 제공 권장.

장점: 개발 편의성(브라우저 API 자유롭게 사용), 저렴한 정적 호스팅, 오프라인 지원
단점: 초기 로드 느림, SEO 불리

---

3. Hybrid Rendering (가장 실용적)

라우트별로 다른 렌더링·캐싱 전략 적용. routeRules로 설정.

// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    '/': { prerender: true },             // 빌드 시 프리렌더링
    '/products': { swr: true },           // 온디맨드 + 백그라운드 재검증
    '/products/**': { swr: 3600 },        // TTL 1시간
    '/blog': { isr: 3600 },              // CDN 캐시 1시간
    '/blog/**': { isr: true },           // 다음 배포까지 CDN 캐시
    '/admin/**': { ssr: false },          // 클라이언트 사이드만
    '/api/**': { cors: true },            // CORS 헤더 자동 추가
    '/old-page': { redirect: '/new-page' }, // 서버사이드 리다이렉트
  },
})

routeRules 속성 정리

속성	설명
prerender: true	빌드 시 정적 HTML 생성
swr: number | boolean	Stale-While-Revalidate. TTL 만료 후 백그라운드 재생성
isr: number | boolean	CDN에 캐시 (Netlify, Vercel 지원). true는 다음 배포까지 유지
ssr: false	해당 경로 CSR 처리
cors: true	CORS 헤더 자동 추가
redirect: string	서버사이드 리다이렉트
headers: object	커스텀 응답 헤더
noScripts: boolean	JS 스크립트 비활성화

⚠️ 주의: Hybrid Rendering은 nuxt generate 명령에서는 사용 불가. nuxt build만 지원.

---

4. Prerendering (Static Site Generation)

nuxt generate  # 또는 nuxt build --prerender

Nitro 크롤러가 루트(/)부터 시작해 링크를 따라가며 모든 페이지를 HTML로 생성.

선택적 프리렌더링

export default defineNuxtConfig({
  nitro: {
    prerender: {
      routes: ['/sitemap.xml', '/user/1', '/user/2'],
      ignore: ['/dynamic'],
      crawlLinks: true,
    },
  },
})

페이지 레벨에서 설정 (experimental.inlineRouteRules: true 필요):

<script setup>
defineRouteRules({ prerender: true })
</script>

Payload 시스템

프리렌더링/ISR/SWR 시 _payload.json이 HTML과 함께 생성됨. 클라이언트 사이드 이동 시 이 페이로드를 불러와 재요청 방지.

---

5. Edge-Side Rendering (ESR)

Nitro 덕분에 CDN 엣지 서버에서 직접 렌더링. 사용자와 물리적으로 가까운 곳에서 응답.

# Vercel Edge
NITRO_PRESET=vercel-edge nuxt build

# Netlify Edge Functions
NITRO_PRESET=netlify-edge nuxt build

# Cloudflare Pages
nuxt build  # 자동 감지

---

배포 모드 선택 가이드

사이트 유형	권장 전략
블로그, 마케팅, 포트폴리오	prerender: true 또는 isr
콘텐츠 + 관리자 섹션	Hybrid (/admin/** → ssr: false)
SaaS, 대시보드	ssr: false (전체 CSR)
전자상거래	Hybrid (상품목록 swr, 상품상세 isr, 장바구니 ssr)

---

참고 / 출처

• reference/3.guide/1.concepts/1.rendering.md
• reference/1.getting-started/15.prerendering.md
• reference/1.getting-started/16.deployment.md