91 lines
9.1 KiB
Markdown
91 lines
9.1 KiB
Markdown
---
|
|
title: official-doc / React Router — Declarative Mode Routing Guide (Routes, Nested Routes, Navigation)
|
|
source_type: official-doc
|
|
url: https://reactrouter.com/start/library/routing
|
|
archive_url:
|
|
related_branches: []
|
|
related_projects: [ca-skeleton-frontend]
|
|
tags: [official-doc, ca-skeleton, frontend, react]
|
|
created: 2026-07-18
|
|
---
|
|
|
|
# official-doc / React Router — Declarative Mode Routing Guide (Routes, Nested Routes, Navigation)
|
|
|
|
> Layer: `raw/` — 외부 자료(공식 문서)의 원문 발췌·출처 기록.
|
|
|
|
## source_type
|
|
|
|
`official-doc` — React Router 공식 문서 (reactrouter.com).
|
|
|
|
## Parent / 활용 branch
|
|
|
|
> 특정 branch 없이 project 차원의 foundational 조사로 수집 (`ca-skeleton-frontend` 의 라우팅 + navigation-guard 계약을 세우기 전 기술 선정 근거).
|
|
|
|
| Parent | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/project-notes/ca-skeleton-frontend-operational-contract]] | client-only Vite SPA 에서 React Router 를 라우팅 + navigation 제어 라이브러리로 채택하는 근거 — `<Routes>`/`<Route>` 컴포넌트 트리로 route 를 선언하고 (파일 기반 프레임워크 컨벤션 없이), nested route 는 `<Outlet/>` 로 합성하며, `Link`/`NavLink` 로 클라이언트 사이드 네비게이션을 제어하는 "Declarative Mode" 형태가 SSR/프레임워크 컨벤션이 필요 없는 Vite-SPA 구조에 부합함을 뒷받침 |
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://reactrouter.com/start/library/routing
|
|
- 아카이브 URL: (미제공)
|
|
- 저자 / 조직: React Router 공식 문서 (reactrouter.com)
|
|
- 발행일: 미상 (문서 자체에 발행일 명시 없음; 본문 상 버전 표기 "React Router v8.2.0" 확인)
|
|
- 마지막 확인일: 2026-07-18
|
|
|
|
**참고**: 요청 URL 경로는 `/start/library/routing` ("library" 라는 표현 포함) 이었으나, WebFetch 로 실제 가져온 본문 타이틀·본문은 "React Router Declarative Mode: Routing Guide" 로 명명되어 있고, 본문 스스로 이 모드를 **"Declarative Mode"** 라고 부른다 (Framework Mode / Data Mode 와 구분 — 아래 §핵심 인용 5번 참조). URL 슬러그의 "library" 와 본문의 "Declarative Mode" 표현이 정확히 동일 용어는 아니므로, 이 둘이 같은 개념이라는 추가 해석은 본 raw 문서에서 단정하지 않는다 (검증되지 않은 추론이므로 §메모 에도 남기지 않음 — wiki 승격 시 별도 확인 필요).
|
|
|
|
## 왜 저장했는지 / Why archived
|
|
|
|
`ca-skeleton-frontend` 는 client-only SPA (Vite 빌드, SSR/프레임워크 컨벤션 없음) 이므로, 라우팅 라이브러리가 파일 기반 프레임워크 규약이나 서버 loader 없이도 route 정의·중첩·네비게이션 제어를 지원하는지 공식 근거로 확인하기 위해 저장. React Router 의 route 선언 API (`<Routes>`/`<Route>`), nested route 합성(`<Outlet/>`), 네비게이션 컴포넌트(`Link`/`NavLink`) 가 이 요구를 충족하는지가 이 자료의 핵심 확인 대상.
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [§Configuring Routes] "Routes are configured by rendering `<Routes>` and `<Route>` components that couple URL segments to UI elements:" — line 9 (fetched text)
|
|
|
|
> [§Nested Routes] "Routes can be nested inside parent routes. The parent's path is automatically included in children:" — line 30 (fetched text)
|
|
|
|
> [§Nested Routes] "Child routes render through the `<Outlet/>` component in the parent:" — line 41 (fetched text)
|
|
|
|
> [§Navigation] "**Key difference:** `NavLink` automatically applies active state styling, while `Link` is a basic navigation element." — line 134 (fetched text)
|
|
|
|
> [문서 하단, mode 구분] "This is **Declarative Mode**, distinct from Framework Mode (file-based routing with conventions) and Data Mode (route objects with data loading/actions)." — line 138 (fetched text)
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| REACT-ROUTER-C1 | React Router 는 `<Routes>`/`<Route>` 컴포넌트를 렌더링해 URL segment 를 UI element 에 결합하는 방식으로 route 를 선언적으로 구성한다 | [§Configuring Routes] "Routes are configured by rendering `<Routes>` and `<Route>` components that couple URL segments to UI elements:" | `official-vendor-doc` | client-side component-tree 기반 route 선언 (파일 기반 프레임워크 컨벤션 불필요) | 성능·번들 크기·프로덕션 준비도는 증명하지 않음. Framework Mode/Data Mode 와의 상세 차이는 이 인용만으로 증명 안 됨 |
|
|
| REACT-ROUTER-C2 | 부모 route 안에 자식 route 를 중첩할 수 있고, 부모의 path 가 자식에 자동 포함되며, 자식 route 는 부모 컴포넌트의 `<Outlet/>` 을 통해 렌더링된다 | [§Nested Routes] "Routes can be nested inside parent routes. The parent's path is automatically included in children:" + "Child routes render through the `<Outlet/>` component in the parent:" | `official-vendor-doc` | 레이아웃 + 자식 페이지 합성 패턴 (예: 인증된 레이아웃 아래 보호된 페이지들을 중첩) | 데이터 로딩(loader)·인가(auth) 로직이 이 중첩 메커니즘에 어떻게 결합되는지는 증명하지 않음 (이는 Data Mode/Framework Mode 영역) |
|
|
| REACT-ROUTER-C3 | `NavLink` 는 활성 상태 스타일링을 자동 적용하고, `Link` 는 기본 네비게이션 엘리먼트라는 점에서 서로 다르다 | [§Navigation] "**Key difference:** `NavLink` automatically applies active state styling, while `Link` is a basic navigation element." | `official-vendor-doc` | 클라이언트 사이드 네비게이션 UI (예: 메뉴 활성 항목 하이라이트) | **navigation guard(인증/인가 기반 라우트 보호) 메커니즘은 증명하지 않음** — 이 인용은 활성 링크 스타일링에 관한 것이며, 라우트 접근 제어(redirect/guard) 로직에 대한 근거가 아님. `ca-skeleton-frontend` 의 navigation-guard 계약에 이 자료를 직접 인용하려면 별도 loader/guard 관련 공식 문서 보강 필요 |
|
|
| REACT-ROUTER-C4 | 본 문서가 다루는 라우팅 방식은 "Declarative Mode" 로 명명되며, 파일 기반 컨벤션을 쓰는 "Framework Mode" 및 데이터 로딩/액션을 route 객체로 다루는 "Data Mode" 와 구분된다 | [문서 하단] "This is **Declarative Mode**, distinct from Framework Mode (file-based routing with conventions) and Data Mode (route objects with data loading/actions)." | `official-vendor-doc` | SSR/파일 기반 프레임워크 컨벤션이 필요 없는 client-only Vite SPA 에 적합한 라우팅 모드 선택의 근거 | Declarative Mode 가 Data Mode 대비 프로덕션에 "권장"된다는 것은 증명하지 않음. 세 모드 간 성능·기능 parity 도 증명하지 않음 |
|
|
|
|
### Strength 근거
|
|
|
|
모든 claim 이 `official-vendor-doc` — reactrouter.com 은 React Router 프로젝트의 공식 문서 사이트이며, 벤더(라이브러리 메인테이너)가 직접 게시하는 레퍼런스 문서.
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- 이 자료가 직접 증명하는 것:
|
|
- `REACT-ROUTER-C1`: `<Routes>`/`<Route>` 컴포넌트 기반 선언적 route 정의 API 존재
|
|
- `REACT-ROUTER-C2`: nested route + `<Outlet/>` 합성 메커니즘 존재
|
|
- `REACT-ROUTER-C3`: `Link` vs `NavLink` 의 활성 스타일링 차이 존재
|
|
- `REACT-ROUTER-C4`: "Declarative Mode" 가 "Framework Mode"(파일 기반 SSR 컨벤션)와 별개로 존재 — 즉 프레임워크 컨벤션 없이도 라우팅을 구성할 수 있음
|
|
- 이 자료가 증명하지 않는 것:
|
|
- **navigation guard(인증 기반 라우트 보호) 메커니즘의 존재나 구현 방식** — 본 발췌에는 loader, redirect, protected-route 패턴에 대한 언급이 전혀 없음. `ca-skeleton-frontend` 의 navigation-guard 결정에는 이 자료만으로 충분한 근거가 아니며, 별도 공식 자료(loader/redirect 또는 인증 가드 관련 문서) 보강 필요 — `UNSUPPORTED_DECISION` 후보
|
|
- 프로덕션 성능/번들 크기/타 라우팅 라이브러리(TanStack Router 등) 대비 우위
|
|
- "library mode" 라는 명칭이 "Declarative Mode" 와 동일 개념이라는 것 (§출처 참고 항목 참조 — 미확인)
|
|
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
|
|
- `ca-skeleton-frontend` 의 실제 route 트리 설계와 이 API 의 정합성 로컬 검증
|
|
- 인증/인가 기반 navigation guard 구현 시 별도 loader/redirect 공식 문서 확보
|
|
|
|
## 메모 / Notes
|
|
|
|
- REACT-ROUTER-C3 는 "네비게이션 제어"의 UI 측면(활성 스타일)만 다루며, 이 문서만으로 "navigation guard"(보호된 라우트) 계약을 정당화할 수 없음 — branch-note 작성 시 이 구분을 명확히 유지할 것.
|
|
- 추가로 봐야 할 동일 출처 페이지: loader/action 기반 데이터 로딩 및 redirect 패턴을 다루는 React Router 공식 문서 (별도 raw 자료로 추가 필요 — navigation-guard 결정의 직접 근거).
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 official-doc: (없음 — 이 자료가 vault 내 첫 React Router 공식 문서)
|
|
- 이 자료를 인용한 wiki 요약: (아직 생성 안 됨)
|