---
type: knowledge
domain: frontend
status: active
last-reviewed: 2026-07-27
---

# 프론트엔드 원리

> 한 줄 정의
> 프레임워크와 무관한 프론트엔드 설계 원리와 선택 기준. React·Next.js 등 구체 기술의 API는 여기 없다 — **공식 문서에서 조회**하고, 여기서는 무엇을 왜 선택할지를 결정한다.

## 렌더링 전략

| 전략 | 선택 조건 |
|------|----------|
| 정적 생성 (빌드 시) | 콘텐츠가 요청과 무관 (마케팅·문서) |
| 서버 렌더링 (요청 시) | SEO 필요 + 사용자별 데이터 |
| 클라이언트 렌더링 | 로그인 후 앱, SEO 무관 (대시보드·도구) |
| 스트리밍 렌더링 | 첫 화면 일부가 느린 데이터에 의존 |

기본값: 페이지 성격별 혼합. "전부 SSR" 같은 일괄 결정을 하지 않는다.

## 상태의 4분류 — 저장소를 섞지 않는다

| 상태 | 원칙 | 도구 계열 |
|------|------|----------|
| 서버 상태 (API 데이터) | 캐시로 취급, 클라이언트 스토어에 복사 금지 | 쿼리 캐시 라이브러리 |
| 클라이언트 상태 (UI) | 사용하는 컴포넌트 근처에 최소로 | 로컬 상태·경량 스토어 |
| URL 상태 | 공유·새로고침에 살아남아야 하면 URL로 (필터·탭·페이지) | 라우터 |
| 폼 상태 | 제출 전 임시 상태로 격리 | 폼 라이브러리 |

안티패턴: 전역 스토어 하나에 전부 넣기, 서버 응답을 스토어에 복제해 이중 진실 만들기.

## 데이터 패칭

- 기본: stale-while-revalidate (캐시 즉시 표시 + 배경 갱신) — 직접 구현하지 말고 라이브러리. 단 잔액·권한·결제처럼 낡은 값 표시가 위험한 데이터는 예외 — 리소스별 신선도는 API 계약에서 정한다.
- 낙관적 업데이트는 롤백·에러 표시와 세트로만.
- 부모-자식 요청 폭포(waterfall) 금지 — 독립 데이터는 병렬로.

## 3상태 원칙

모든 데이터 화면은 **로딩·빈 값·에러** 3상태를 명시적으로 설계한다. 성공 화면만 만드는 것이 AI의 대표 실수다 ([[AI-실수패턴]] #7). 3상태는 최소 부분집합이다 — 납품 명세는 권한 없음·완료·오프라인까지 7상태 매트릭스로 확장된다 ([[03_화면·상태 명세]]).

## AI 응답 UX (LLM 기능이 있을 때)

- **스트리밍 기본**: 토큰 단위 표시 + 중단 버튼. 전체 대기 스피너는 최후 수단.
- **에이전트 실행 상태 노출**: 대기→실행→도구 호출(무엇을)→완료/실패를 단계로 보여준다. 블랙박스 30초는 이탈이다.
- **승인 UI (HITL)**: 승인 대상의 전문 표시 · 수정 후 승인 가능 · 거절 사유 입력 · 승인 이력. → [[Human In the Loop]]
- **실패 UX**: AI 실패는 정상 상황이다 — 재시도·문의·수동 폴백 경로를 화면에 둔다.
- 실시간 채널 선택: 단방향 진행 표시는 SSE, 양방향 협업만 WebSocket.

## 인증 흐름

- 토큰 보관 기본값: httpOnly 쿠키 — 스크립트의 토큰 탈취만 막을 뿐 XSS 방어책 자체가 아니며, 쿠키 인증은 CSRF 대책(SameSite·CSRF 토큰)과 세트다 ([[인증 구현 실전]] 세션 보안). localStorage 보관은 근거 있을 때만.
- 만료 처리: 401 → 리프레시 → 재시도 1회 → 로그인 이동. 이 흐름을 데이터 레이어 한 곳에 — 동시 401 다발은 리프레시 1회로 합친다(single-flight).

## 성능·접근성·테스트

한 줄 요약만 — 실전 정본은 03_품질·운영: [[웹 성능 실전]] · [[접근성 실전]] · [[프론트엔드 테스트 실전]].

- 성능: 이미지 크기 명시(CLS 방지), 코드 스플리팅은 라우트 단위 기본, 무거운 라이브러리는 동적 import.
- 접근성 최소선: 시맨틱 마크업, 키보드 탐색, 포커스 표시, 대비.
- 테스트 우선순위: ① 유틸·훅 단위 ② 사용자 행동 컴포넌트 테스트 ③ 핵심 여정 E2E 소수 — 배분·도구 규율은 [[프론트엔드 테스트 실전]]이 정본.

## 관련 문서

- [[00_프론트엔드 허브]] · [[03_프론트엔드 설계]] — 설계 결정·납품 연결
- [[프론트엔드-체크리스트]] · [[API-명세-템플릿]] · [[백엔드 원리]] · [[보안-체크리스트]] · [[UX 원리]] · [[UI 시각 체계]]