SSR에서 사용하기

Sonamu의 SSR 라우트에 cacheControl 옵션을 추가하여 SSR 페이지 응답에 Cache-Control 헤더를 설정할 수 있습니다.

기본 사용법

registerSSR에 추가

import { registerSSR, CachePresets } from "sonamu";
import ProductList from "./pages/ProductList";

registerSSR({
  path: '/products',
  Component: ProductList,
  cacheControl: CachePresets.ssr,  // SSR 최적화
});

결과:

HTTP/1.1 200 OK
Cache-Control: public, max-age=10, stale-while-revalidate=30
Content-Type: text/html

<!DOCTYPE html>
<html>...</html>

SSR 캐싱 전략

SSR 프리셋

가장 권장하는 방법은 CachePresets.ssr을 사용하는 것입니다.

registerSSR({
  path: '/products/:id',
  Component: ProductDetail,
  cacheControl: CachePresets.ssr,
});

CachePresets.ssr:

{
  visibility: 'public',
  maxAge: 10,  // 10초 동안 Fresh
  staleWhileRevalidate: 30  // 이후 30초 동안 Stale 사용
}

작동 방식

장점:

대부분의 요청이 즉시 응답 (CDN 캐시)
Stale 기간에도 빠른 응답
백그라운드 갱신으로 항상 최신 상태 유지

페이지 유형별 전략

동적 페이지
준동적 페이지
정적 페이지
개인화 페이지

자주 변경되는 콘텐츠

// 게시글 목록
registerSSR({
  path: '/posts',
  Component: PostList,
  cacheControl: CachePresets.shortLived,  // 1분
});

// 실시간 대시보드
registerSSR({
  path: '/dashboard',
  Component: Dashboard,
  cacheControl: CachePresets.noCache,  // 매번 재검증
});

가끔 변경되는 콘텐츠

// 상품 상세
registerSSR({
  path: '/products/:id',
  Component: ProductDetail,
  cacheControl: CachePresets.ssr,  // 10초 + SWR 30초
});

// 블로그 글
registerSSR({
  path: '/blog/:slug',
  Component: BlogPost,
  cacheControl: {
    visibility: 'public',
    maxAge: 300,  // 5분
    staleWhileRevalidate: 900,  // 15분
  }
});

거의 변경되지 않는 콘텐츠

// 회사 소개
registerSSR({
  path: '/about',
  Component: About,
  cacheControl: CachePresets.longLived,  // 1시간
});

// 이용 약관
registerSSR({
  path: '/terms',
  Component: Terms,
  cacheControl: {
    visibility: 'public',
    maxAge: 86400,  // 1일
  }
});

사용자별로 다른 콘텐츠

// 마이페이지
registerSSR({
  path: '/my/profile',
  Component: MyProfile,
  cacheControl: CachePresets.private,  // 브라우저만 캐싱
});

// 장바구니
registerSSR({
  path: '/cart',
  Component: Cart,
  cacheControl: CachePresets.noStore,  // 캐시 금지
});

실전 예제

1. 전자상거래 사이트

// 홈페이지: SSR 최적화
registerSSR({
  path: '/',
  Component: HomePage,
  cacheControl: CachePresets.ssr,  // 10초 + SWR 30초
});

// 상품 목록: 짧은 캐시
registerSSR({
  path: '/products',
  Component: ProductList,
  cacheControl: CachePresets.shortLived,  // 1분
});

// 상품 상세: SSR 최적화
registerSSR({
  path: '/products/:id',
  Component: ProductDetail,
  cacheControl: CachePresets.ssr,
});

// 카테고리: 긴 캐시
registerSSR({
  path: '/categories/:id',
  Component: CategoryPage,
  cacheControl: CachePresets.mediumLived,  // 5분
});

// 장바구니: 개인화
registerSSR({
  path: '/cart',
  Component: Cart,
  cacheControl: CachePresets.private,
});

// 주문 완료: 캐시 금지
registerSSR({
  path: '/orders/:id/complete',
  Component: OrderComplete,
  cacheControl: CachePresets.noStore,
});

2. 블로그

// 홈페이지
registerSSR({
  path: '/',
  Component: HomePage,
  cacheControl: {
    visibility: 'public',
    maxAge: 300,  // 5분
    staleWhileRevalidate: 900,  // 15분
  }
});

// 카테고리별 목록
registerSSR({
  path: '/category/:slug',
  Component: CategoryPosts,
  cacheControl: CachePresets.mediumLived,  // 5분
});

// 게시글 상세
registerSSR({
  path: '/posts/:slug',
  Component: PostDetail,
  cacheControl: {
    visibility: 'public',
    maxAge: 600,  // 10분
    staleWhileRevalidate: 1800,  // 30분
  }
});

// 검색 결과
registerSSR({
  path: '/search',
  Component: SearchResults,
  cacheControl: CachePresets.shortLived,  // 1분
});

3. SaaS 대시보드

// 공개 랜딩 페이지
registerSSR({
  path: '/',
  Component: Landing,
  cacheControl: CachePresets.longLived,  // 1시간
});

// 로그인 후 대시보드
registerSSR({
  path: '/dashboard',
  Component: Dashboard,
  cacheControl: CachePresets.private,  // 브라우저만
});

// 사용자 설정
registerSSR({
  path: '/settings',
  Component: Settings,
  cacheControl: CachePresets.noStore,  // 캐시 금지
});

CSR Fallback

SSR 라우트에 매칭되지 않는 모든 요청은 CSR fallback으로 처리됩니다.

// CSR fallback 라우트 (catch-all)
registerSSR({
  path: '/*',
  Component: App,
  cacheControl: CachePresets.shortLived,  // 1분
});

작동 방식:

/products/1 → SSR 라우트 매칭 → 해당 cacheControl 사용
/random-page → SSR 라우트 미매칭 → fallback cacheControl 사용

전역 핸들러

모든 SSR 페이지에 일괄적으로 Cache-Control을 적용할 수 있습니다.

// sonamu.config.ts
import { CachePresets, type SonamuConfig } from "sonamu";

export const config: SonamuConfig = {
  server: {
    apiConfig: {
      cacheControlHandler: (req) => {
        // SSR 요청만 처리
        if (req.type !== 'ssr') {
          return undefined;
        }
        
        // 경로별 처리
        if (req.path === '/') {
          return CachePresets.ssr;  // 홈페이지
        }
        
        if (req.path.startsWith('/admin/')) {
          return CachePresets.noStore;  // 관리 페이지
        }
        
        if (req.path.startsWith('/my/')) {
          return CachePresets.private;  // 개인 페이지
        }
        
        // 기본값: SSR 프리셋
        return CachePresets.ssr;
      }
    }
  }
};

SSRRoute 객체 활용

cacheControlHandler: (req) => {
  if (req.type !== 'ssr') return undefined;
  
  // SSRRoute 정보 활용
  if (req.route) {
    const { path } = req.route;
    
    // 동적 라우트 체크
    if (path.includes(':')) {
      return CachePresets.ssr;  // 상세 페이지
    }
    
    // 정적 라우트
    return CachePresets.mediumLived;  // 목록 페이지
  }
  
  return CachePresets.shortLived;
}

우선순위

SSR Cache-Control 설정은 다음 순서로 적용됩니다:

registerSSR의 cacheControl (가장 우선)
cacheControlHandler 반환값
기본값 (Cache-Control 헤더 없음)

Vary 헤더

다국어 SSR 페이지에서 Vary 헤더를 사용합니다.

registerSSR({
  path: '/products/:id',
  Component: ProductDetail,
  cacheControl: {
    visibility: 'public',
    maxAge: 300,
    vary: ['Accept-Language'],  // 언어별 캐시 분리
  }
});

결과:

GET /products/1 (Accept-Language: ko) → 한국어 HTML 캐싱
GET /products/1 (Accept-Language: en) → 영어 HTML 캐싱

CDN 최적화

CloudFront + Stale-While-Revalidate

AWS CloudFront는 stale-while-revalidate를 지원합니다.

registerSSR({
  path: '/products/:id',
  Component: ProductDetail,
  cacheControl: {
    visibility: 'public',
    maxAge: 60,  // 1분
    sMaxAge: 300,  // CDN: 5분
    staleWhileRevalidate: 600,  // 10분간 Stale 사용
  }
});

효과:

브라우저: 1분마다 CDN 요청
CDN: 5분마다 서버 요청
Stale: 최대 15분(5분 + 10분) 동안 빠른 응답

정적 자산과 조합

// SSR 페이지
registerSSR({
  path: '/products/:id',
  cacheControl: CachePresets.ssr,  // 10초
});

// 정적 파일 (별도 설정)
server.get('/assets/:filename', (req, reply) => {
  if (req.params.filename.includes('-')) {  // 해시 포함
    applyCacheHeaders(reply, CachePresets.immutable);  // 1년
  }
  return reply.sendFile(req.params.filename);
});

결과:

HTML: 10초마다 갱신 (최신 콘텐츠)
JS/CSS: 1년 캐시 (빠른 로딩)

프리로딩과 캐싱

SSR의 preload 기능과 Cache-Control을 조합합니다.

registerSSR({
  path: '/products/:id',
  Component: ProductDetail,
  preload: (params) => [
    {
      modelName: 'ProductModel',
      methodName: 'findById',
      params: ['A', Number(params.id)],
      serviceKey: ['Product', 'getProduct'],
    }
  ],
  cacheControl: CachePresets.ssr,
});

효과:

SSR 시: 서버에서 데이터 프리로드 → HTML 생성 → 캐싱
캐시 히트: CDN에서 즉시 HTML 반환 (빠름)
Hydration: 클라이언트에서 프리로드된 데이터 사용

개인화 페이지 처리

인증 필요한 페이지

// 로그인 필요한 페이지
registerSSR({
  path: '/my/profile',
  Component: MyProfile,
  cacheControl: CachePresets.private,  // 브라우저만 캐싱
});

// 또는 캐시 금지
registerSSR({
  path: '/my/orders',
  Component: MyOrders,
  cacheControl: CachePresets.noStore,
});

조건부 SSR

사용자 상태에 따라 다른 페이지를 렌더링하는 경우:

registerSSR({
  path: '/dashboard',
  Component: Dashboard,
  cacheControl: {
    visibility: 'private',  // private 필수
    noCache: true,  // 매번 재검증
    vary: ['Cookie'],  // 쿠키별 캐시 분리
  }
});

주의사항

SSR Cache-Control 사용 시 주의사항:

개인화 페이지는 private 또는 no-store: CDN 캐싱 방지

// ❌ 위험: 개인 페이지가 CDN에 캐싱
registerSSR({
  path: '/my/profile',
  cacheControl: { visibility: 'public', maxAge: 60 }
})

// ✅ 안전
registerSSR({
  path: '/my/profile',
  cacheControl: CachePresets.private
})

동적 콘텐츠는 짧은 TTL: 오래된 HTML 방지

// ❌ 실시간 대시보드인데 1시간 캐싱
registerSSR({
  path: '/dashboard',
  cacheControl: CachePresets.longLived
})

// ✅ 짧은 TTL 또는 no-cache
registerSSR({
  path: '/dashboard',
  cacheControl: CachePresets.shortLived
})

인증 쿠키 고려: Vary 헤더로 분리

registerSSR({
  path: '/dashboard',
  cacheControl: {
    visibility: 'private',
    maxAge: 60,
    vary: ['Cookie'],  // 쿠키별 캐시 분리
  }
})

CSR fallback 설정: 매칭되지 않는 라우트 처리

// 마지막에 catch-all 라우트 추가
registerSSR({
  path: '/*',
  Component: App,
  cacheControl: CachePresets.shortLived,
})

디버깅

Cache-Control 헤더 확인

브라우저 개발자 도구에서 확인:

Network 탭 → 요청 선택 → Headers 탭
Response Headers:
  Cache-Control: public, max-age=10, stale-while-revalidate=30
  Vary: Accept-Language

CDN 캐시 상태

CDN별로 캐시 상태 헤더를 제공합니다: CloudFront:

X-Cache: Hit from cloudfront
Age: 5

Cloudflare:

CF-Cache-Status: HIT
Age: 5

다음 단계

Cache-Control이란?

HTTP 캐싱 기본 개념

Cache Presets

사전 정의된 캐시 설정

API에서 사용하기

@api 데코레이터에 적용

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

​기본 사용법

​registerSSR에 추가

​SSR 캐싱 전략

​SSR 프리셋

​작동 방식

​페이지 유형별 전략

​실전 예제

​1. 전자상거래 사이트

​2. 블로그

​3. SaaS 대시보드

​CSR Fallback

​전역 핸들러

​SSRRoute 객체 활용

​우선순위

​Vary 헤더

​CDN 최적화

​CloudFront + Stale-While-Revalidate

​정적 자산과 조합

​프리로딩과 캐싱

​개인화 페이지 처리

​인증 필요한 페이지

​조건부 SSR

​주의사항

​디버깅

​Cache-Control 헤더 확인

​CDN 캐시 상태

​다음 단계