clean-architecture-frontend-template/docs/architecture/decisions/VD-03-react-router-data-mode.md

VD-03: React Router Data Mode와 서버 상태 소유권

• 상태: Accepted
• 결정일: 2026-07-26
• 적용 브랜치: feature-frontend-routing-release-recovery-runtime

배경

기존 라우터는 BrowserRouter와 수동 JSX route 목록을 사용했다. 직렬화 가능한 route registry에 params/search schema, loading/error surface, access, title, navigation과 chunk ID가 있었지만 실행 route tree와 독립적이어서 선언과 행동이 어긋날 수 있었다.

이 저장소는 client-only SPA이며 서버 상태는 application input과 TanStack Query가 소유한다. Framework Mode의 loader/action 중심 데이터 소유권이나 SSR을 도입하지 않으면서 route object, 오류 경계와 navigation lifecycle은 중앙에서 조립할 필요가 있다.

결정

1. 고정된 React Router 7.18.1의 createBrowserRouter와 RouterProvider를 사용하는 Data Mode를 기본값으로 채택한다.
2. 직렬화 가능한 route contract와 React component/codec runtime map을 분리한다.
3. 모든 executable route object와 navigation은 registry에서 생성한다. JSX에서 route 목록을 다시 열거하지 않는다.
4. params/search는 route 경계의 Zod codec으로 parse하고 같은 codec으로 canonical URL을 생성한다.
5. loader/action은 같은 서버 데이터를 직접 다시 요청하지 않는다. 필요하면 application input 또는 query adapter 한 경로를 호출한다.
6. 서버 상태, retry, cache와 mutation lifecycle은 application input과 TanStack Query가 계속 소유한다.
7. lazy chunk rejection만 release recovery input으로 보내며 일반 render error는 route/feature boundary가 소유한다.
8. Framework Mode, SSR, static generation과 router version upgrade는 별도 dependency/architecture 브랜치에서 결정한다.

검증

• route contract/runtime map의 누락과 orphan은 TypeScript negative fixture와 registry gate가 모두 거절한다.
• duplicate ID/path, unknown codec/surface/chunk와 참조 불일치를 negative registry fixture로 검증한다.
• params/search parse/build round-trip, canonical redirect, 최대 redirect hop, access rejection, title/focus와 boundary reset을 unit/component test로 검증한다.
• Vite dynamic entry와 release route chunk map, runtime config JSON Schema를 build/release 검증기가 확인한다.
• chunk failure는 no-store manifest refetch 후 build/release 쌍마다 한 번만 reload하며 offline, malformed manifest와 storage 실패는 fail-closed한다.

결과와 rollback

Data Router는 navigation lifecycle의 조립 경계이며 서버 데이터 계층이 아니다. 이 구분을 지키면 React Router를 교체해도 application input과 output port는 유지된다.

rollback은 RP-04 merge를 되돌려 이전 수동 router와 generic route failure surface로 복구한다. URL shape와 application API는 유지하고, 이미 배포된 asset cache의 purge는 저장소 rollback 범위에 포함하지 않는다.