ADR-0004: 인증이 필요한 화면을 클라이언트 렌더링으로 고정한다
상태
Accepted
날짜
2026-08-10
맥락
Angular SSR을 활성화한 상태에서 경로별 렌더링 모드를 정해야 합니다. Angular CLI가 생성한 기본 설정은 모든 경로(**)를 RenderMode.Prerender로 두는데, 이는 업무 화면에 맞지 않습니다. 파라미터가 있는 경로는 getPrerenderParams 없이 생성되지 않고, 사용자별 데이터는 빌드 시점에 알 수 없습니다.
핵심 제약은 서버가 인증 상태를 알 수 있는가입니다.
| 토큰 보관 | 서버의 인식 | 서버 렌더링의 실효 |
|---|---|---|
| httpOnly 쿠키 | 요청 쿠키로 인식 | 인증 데이터까지 렌더링 가능 |
| 메모리 · Storage | 인식 불가 | 빈 껍데기만 렌더링. 데이터는 하이드레이션 후 조회 |
즉 인증 화면에서 서버 렌더링이 값을 가지려면 토큰을 httpOnly 쿠키로 강제해야 하고, 이는 백엔드의 인증 방식을 규정하는 결정이 됩니다. 본 문서는 여러 프로젝트에 적용하는 규범집이므로 백엔드 방식을 강제할 수 없습니다.
결정
경로별 렌더링 모드를 다음과 같이 고정합니다.
| 경로 | 모드 |
|---|---|
| 공개 경로 (랜딩, 로그인, 약관 등) | RenderMode.Prerender |
그 외 전체 (**) |
RenderMode.Client |
RenderMode.Server는 사용하지 않습니다.
정적 생성 대상은 명시적으로 열거한 경로만 받습니다. **를 Client로 두는 이유는 예측 가능성입니다. 규칙을 모르는 사람이나 에이전트가 라우트를 추가해도 기본값이 안전한 쪽으로 떨어져 빌드가 깨지지 않습니다.
세부 규칙은 렌더링 전략이 원본입니다.
검토한 대안
전면 Server 렌더링 + httpOnly 쿠키 인증
| 구분 | 내용 |
|---|---|
| 장점 | 인증 화면도 데이터까지 서버에서 렌더링되어 초기 로딩이 가장 빠릅니다. 토큰이 JS로 읽히지 않아 XSS 탈취 위험이 줄어듭니다 |
| 단점 | 백엔드가 쿠키 기반 인증을 지원해야 하며 CSRF 대응이 필요합니다. 서버가 요청별 인증 컨텍스트를 다루게 되어 상태 오염 위험이 생깁니다. 하이드레이션 불일치 디버깅 비용이 발생합니다 |
| 기각 사유 | 규범집이 백엔드 인증 방식을 강제하게 됩니다. 프로젝트별로 쿠키 방식을 쓸 수 없는 경우 이 표준을 적용할 수 없게 됩니다 |
전면 Server 렌더링, 데이터는 클라이언트에서 조회
| 구분 | 내용 |
|---|---|
| 장점 | 토큰 보관 방식을 강제하지 않으면서 레이아웃 골격이 빨리 표시됩니다 |
| 단점 | LCP는 대개 데이터에 걸려 있어 체감 개선이 작습니다. 서버 렌더링 비용과 하이드레이션 불일치 위험은 그대로 치릅니다 |
| 기각 사유 | 치르는 비용에 비해 얻는 것이 확인되지 않았습니다. 측정 없이 도입할 근거가 없습니다 |
SSR을 끄고 순수 SPA로 전환
| 구분 | 내용 |
|---|---|
| 장점 | 렌더링 경계라는 축 자체가 사라져 문서가 줄고 브라우저 전용 코드 격리 규칙도 불필요해집니다 |
| 단점 | 공개 페이지의 검색 노출과 초기 페인트를 포기합니다 |
| 기각 사유 | 공개 페이지의 정적 생성은 비용이 거의 없으면서 이득이 명확합니다. 축 전체를 제거할 이유가 되지 않습니다 |
결과
토큰 보관 방식을 프로젝트가 자유롭게 정할 수 있습니다. 백엔드와의 사전 협의 없이 이 표준을 적용할 수 있습니다.
업무 화면 전체가 클라이언트 렌더링이므로 적응형 UI의 하이드레이션 불일치 위험에서 벗어납니다. 서버에는 포인터와 뷰포트가 없어 적응형 컴포넌트가 정적 생성 경로에서 문제를 일으키는데, 업무 화면은 정적 생성 대상이 아니므로 이 제약을 받지 않습니다.
감수하는 사항은 다음과 같습니다.
- SSR을 켠 이득이 공개 경로에만 국한됩니다. 업무 화면의 초기 로딩은 순수 클라이언트 렌더링과 동일합니다. 개선은 번들 축소와 지연 로딩으로 달성하며 서버 렌더링으로 해결하지 않습니다.
- 증분 하이드레이션의 효과도 공개 경로로 제한됩니다. Angular 22에서 기본 활성화되어 있으나 하이드레이션할 서버 HTML이 있는 경로에서만 의미를 갖습니다.
- 공개 경로에서는 적응형 컴포넌트를 사용할 수 없습니다. CSS 미디어 쿼리로 해결되는 반응형만 사용하며, 이 제약은 자동 강제되지 않아 코드 리뷰에서 확인합니다.