렌더링 모드

같은 Nuxt 앱이라도 페이지를 어디서·언제 그리느냐에 따라 성능과 SEO가 크게 달라집니다. Nuxt는 서버 렌더링(SSR), 클라이언트 렌더링(SPA), 정적 생성(SSG)을 모두 지원하며, 심지어 페이지마다 다르게 설정할 수도 있습니다. 이번 레슨에서 각 모드의 차이와 선택 기준을 정리합니다.

학습 목표

• 유니버설(SSR)·SPA(CSR)·SSG의 동작 방식을 구분한다.
• 하이드레이션이 무엇인지 이해한다.
• routeRules 로 경로별 렌더링을 혼합한다.
• 상황별로 어떤 모드를 골라야 할지 판단한다.

세 가지 모드 한눈에

모드	HTML을 만드는 시점·위치	장점	약점
유니버설(SSR)	요청마다 서버에서	SEO·초기 표시 빠름	서버 필요
SPA(CSR)	브라우저에서	서버 부담 적음	초기 로딩·SEO 불리
SSG(prerender)	빌드 시 미리	매우 빠름·CDN 배포	동적 콘텐츠 약함

유니버설 렌더링 (기본값, SSR)

Nuxt의 기본 모드입니다. 요청이 오면 서버에서 완성된 HTML 을 만들어 보내고, 브라우저는 이를 곧바로 보여줍니다. 검색 엔진과 사용자가 빈 화면 없이 콘텐츠를 즉시 받습니다.

// nuxt.config.ts — 기본값이라 따로 설정할 필요 없음
export default defineNuxtConfig({
  ssr: true,
});

하이드레이션

서버가 보낸 정적 HTML은 그대로는 클릭·입력에 반응하지 않습니다. 브라우저에서 Vue가 다시 살아나며 이벤트를 붙이는 과정을 하이드레이션(hydration) 이라고 합니다.

[서버] HTML 생성  →  [브라우저] HTML 표시  →  [브라우저] JS 로드 → 하이드레이션 → 인터랙션 가능

⚠️ 주의 — 서버와 클라이언트의 렌더 결과가 다르면 하이드레이션 불일치 경고가 납니다. Date.now() 나 Math.random() 처럼 매번 달라지는 값을 템플릿에 직접 쓰지 마세요.

SPA 모드 (CSR)

서버 렌더링을 끄면 순수 클라이언트 렌더링이 됩니다. 첫 응답은 빈 껍데기 HTML이고, JS가 로드된 뒤 브라우저가 화면을 그립니다. 로그인 뒤에만 보이는 관리자 도구처럼 SEO가 필요 없는 앱에 적합합니다.

export default defineNuxtConfig({
  ssr: false, // 전체 앱을 SPA로
});

정적 생성 (SSG / prerender)

nuxt generate 로 빌드 시점에 모든 페이지를 미리 HTML로 만들어 둡니다. 서버 없이 정적 호스팅(CDN)에 올릴 수 있어 가장 빠르고 저렴합니다. 블로그·문서·랜딩 페이지에 잘 맞습니다.

npx nuxi generate

routeRules 로 혼합하기

가장 강력한 점은 경로마다 다른 모드 를 줄 수 있다는 것입니다. nuxt.config.ts 의 routeRules 로 설정합니다.

export default defineNuxtConfig({
  routeRules: {
    // 마케팅 페이지: 빌드 시 미리 생성 (SSG)
    '/': { prerender: true },
    // 블로그: 일정 시간 캐시 (ISR 유사)
    '/blog/**': { isr: 3600 },
    // 관리자: 클라이언트에서만 렌더 (SPA)
    '/admin/**': { ssr: false },
    // API: CORS 헤더 추가
    '/api/**': { cors: true },
  },
});

규칙	의미
prerender: true	빌드 때 정적 HTML로 생성
isr: <초>	점진적 정적 생성 (지정 시간마다 갱신)
ssr: false	해당 경로만 SPA로
redirect	다른 경로로 리디렉션
headers / cors	응답 헤더 설정

언제 무엇을 쓸까

• 콘텐츠가 고정 되어 있다(블로그·문서·랜딩) → SSG(prerender).
• 자주 바뀌지만 SEO가 중요 하다(상품·뉴스) → SSR 또는 isr.
• 로그인 뒤에만 쓰고 SEO 불필요 하다(대시보드) → SPA(ssr: false).
• 대부분 SSR이되 일부만 다르게 → 기본 SSR + routeRules 로 예외 처리.

💡 TIP — 처음에는 기본 SSR로 시작하고, 트래픽·SEO 요구가 분명해지는 페이지부터 routeRules 로 최적화하는 방식이 안전합니다.

요약

• 기본은 유니버설(SSR): 서버에서 HTML을 만들고 브라우저에서 하이드레이션합니다.
• ssr: false 면 SPA, nuxt generate 면 SSG입니다.
• routeRules 로 경로마다 렌더링 모드를 섞을 수 있습니다.
• 콘텐츠 성격(고정/동적/비공개)에 맞춰 모드를 고릅니다.

연습문제

1. nuxt.config.ts 에서 ssr: false 로 두고 첫 응답 HTML이 어떻게 달라지는지 관찰해 보세요.
2. routeRules 로 / 는 prerender: true, /admin/** 는 ssr: false 로 설정해 보세요.
3. 하이드레이션 불일치 경고를 일부러 일으켜 보고(Math.random() 등), <ClientOnly> 로 해결해 보세요.
4. 블로그·관리자·상품 페이지에 각각 어떤 모드가 적합한지 이유와 함께 정리해 보세요.

힌트 — 경로별 설정은 모두 routeRules 한 곳에 모이며, 전역 기본값은 ssr 옵션으로 정합니다.