Files
clean-architecture-frontend…/docs/architecture/routing-pages-and-patterns.md
T
DongHyeonka 298201f3ee perf(features)!: 기능 실행부를 초기 청크에서 떼어 라우트 진입 때 적재한다 (15-01)
문제
초기 JS는 203,572 / 204,800 B(gzip)였다. 생성 인덱스가 각 기능의
feature-module.ts를 정적으로 import하고, 그 파일이 계약(zod 스키마·mapper
포함), HTTP 계약 contribution, application input 팩토리, route codec까지
모두 끌고 왔다. 참조 모양 기능 1개를 더하면 +3,922 B가 늘어 첫 기능에서
예산을 넘었다.

고른 방법
- 기능을 두 부분으로 나눈다. 선언(FeatureModule: route 표, route runtime
  계약, invalidation, 문구, 부팅 때 release manifest와 맞춰 볼
  contractPackages)은 초기 청크에 남는다. 실행부(FeatureRuntime: V2 API
  계약, adapter contribution, contract contribution)는 feature-runtime.ts로
  옮기고 loadRuntime이 동적 import한다. route codec은 context-routes.ts의
  route handle에 실어 route와 함께 적재한다.
- 적재 시점은 그 기능의 route에 들어갈 때다. ContextRouteGateway가 route
  모듈과 함께 application.features.load(featureId)를 부르고, 끝난 뒤에
  화면을 그린다(공개 포트에는 load만 추가). 들어온 URL의 기능은 route
  모듈과 병렬로 적재해 왕복을 늘리지 않는다. 런타임 설정으로 꺼진 기능은
  적재하지 않는다.
- 조립부는 기능별 로더를 만든다(installed-feature-adapters.ts). contract
  registry는 기능이 적재될 때마다 전체를 다시 합쳐 검증한다
  (installed-contract-contributions.ts). 선언하지 않은 contract package를
  적재하면 거절한다.
- 모든 실행부를 한꺼번에 읽는 registry(V2 API, contract contribution)는
  installed-feature-runtime-registries.ts의 async 함수로, Node·테스트·
  registry 거버넌스용 상수는 top-level await 모듈 loaded-feature-runtimes.ts로
  둔다. src에서 후자를 import하면 새 아키텍처 규칙
  boot-does-not-load-every-feature-runtime이 막는다. 플랫폼 구성 화면은
  route 로더에서 async 함수를 불러 결과를 prop으로 받는다.
- vite.config.ts에 청크 그룹 2개를 둔다. rolldown은 부팅 그래프와 lazy
  청크가 같이 쓰는 모듈을 importer 집합마다 따로 청크로 뗀다. 그대로 두면
  기능마다 선언 청크가 하나씩 늘고(기능당 +1,471 B), 실행부와 공유하는
  플랫폼 모듈(HTTP executor, contract runtime, zod)이 6개 청크로 쪼개져
  템플릿 자체가 +438 B 커졌다. feature-declarations는 모든 기능의 선언을,
  feature-platform은 실행부가 같이 쓰는 부팅 모듈을 한 청크로 묶는다.
  render-boot-failure.tsx가 쓰는 모듈은 feature-platform에서 뺀다(09-03:
  애플리케이션 그래프가 평가 중 던져도 실패 화면은 떠야 한다).

버린 대안
- 부팅 때 feature 청크를 미리 동적 import하고 기다린 뒤 렌더: 분류기는
  lazy로 세지만 첫 렌더 경로의 바이트는 그대로다. 예산을 속이는 것이라
  버렸다.
- 실행부 일부만 지연(adapter와 contribution만): 모두 같은 zod 스키마를
  공유해 줄지 않았다. 실측 +4,031 B로 오히려 늘었다.
- 선언과 실행부를 같은 lazy 청크(context-routes)에 두기: 기능당
  -60 B 수준이라 그룹 없이 목표에 못 미쳤다.
- 페이지 문구까지 실행부로 옮기기: 기능당 약 300~450 B를 더 줄이지만
  i18n catalog를 런타임 등록 구조로 바꿔야 해 이번 범위에서 뺐다.
- boot.tsx를 별도 진입점으로 추가: 분류기가 boot의 동적 import를 모두
  초기로 세어 218,303 B가 됐다.

위험·한계
- FeatureModule 모양이 바뀐다. 다운스트림 기능은 feature-runtime.ts로
  실행부를 옮겨야 한다(BREAKING CHANGE).
- 기능 계약 간 중복(operation, schema, contribution) 검사가 부팅이 아니라
  그 기능의 적재 시점과 Node 검사(loaded-feature-runtimes를 읽는 스크립트·
  테스트)로 옮겨 간다.
- 기능 route에 처음 들어갈 때 실행부 청크(약 5 KB gzip)를 받는다. 플랫폼
  구성 화면은 모든 기능의 실행부를 받은 뒤 그린다. lab 게이트(FE-GATE-026)가
  재는 화면이라 LCP가 조금 늘 수 있다. 측정하지 않았다.
- 청크 그룹은 rolldown 자동 분할을 일부 대신한다. feature-declarations가
  비면 기능당 증가 상한 테스트가 실패한다. feature-platform이 비면 템플릿
  총량(약 2 KB)만 늘고 번들 예산 검사가 잡는다.
- config/contracts/registry-baseline.json의 FE-REG-API/SCHEMA source는 아직
  installed-feature-contracts.ts다. 승인 digest가 걸려 있어 소유자 재승인
  때 고친다. check-registries는 통과한다.
- 예산 안에 들어가는 참조 모양 기능은 약 3개다. 플랫폼 자체가 예산의
  98.8%다.

수치 (vite build, classifyViteJavascript + gzipSync 기본 수준)
- 템플릿: 203,572 B(13파일) -> 202,361 B(16파일), -1,211 B
- 참조 복사본 +1: 207,494 B(+3,922) -> 203,102 B(+741)
- 참조 복사본 +2: 210,818 B(+3,324) -> 203,750 B(+648)
- 참조 복사본 +5: 205,629 B
- lazy JS: 23,516 B -> 28,204 B

검증
- RED: node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts
  "adds at most 1 KiB ... (15-01)" 실패: expected 3934 to be less than or
  equal to 1024
- GREEN: 같은 테스트 통과(+741 B)
- node scripts/run-vitest.ts run tests/unit: 168파일 2,383 통과
- node scripts/run-vitest.ts run tests/component tests/features
  tests/integration tests/contract tests/runtime-schema tests/architecture
  tests/platform tests/recipes (security-followup-archive 제외, pnpm 호출):
  109파일 787 통과
- npx tsc --noEmit: app, node, test, recipes, web-worker, service-worker 통과
- npx eslint 바뀐 파일 통과
- check-architecture.ts(pnpm exec 대신 eslint를 부르는 shim): PASS, 새 규칙이
  boot.tsx의 import를 거절하는 것 확인
- check-adapter-inventory, check-registries, verify-documentation-readiness,
  check-ci-contract: PASS
- e2e Chromium 전체(pnpm 없는 build-frontend + vite preview, 별도 포트):
  55 통과
- storybook build 성공
- 미실행: Firefox·WebKit e2e, 시각 회귀, lab 성능(FE-GATE-026),
  pnpm 경로의 check:bundle, test:system

BREAKING CHANGE: FeatureModule은 id, contracts(선언), routes, messages,
  loadRuntime만 가진다. adapters, contractContributions와 V2 API 계약
  (apiOperations, schemas, runtimeSchemas, mappers)은 defineFeatureRuntime으로
  만든 feature-runtime.ts로, route codec은 context-routes.ts의 route handle
  codecs로 옮긴다. contracts에는 contractPackages를 추가한다.
Refs: docs/reviews/2026-11-01-maturity-review/15-performance.md 15-01,
  16-structure-patterns.md 9절
2026-11-01 21:57:53 +09:00

21 KiB

라우팅, 페이지 템플릿, 재사용 패턴

정본 안내 (non-authoritative for runtime capability decisions)

Runtime Config/boot, Fetch HTTP client, Router, Query/Mutation, realtime 공통 경계, Web Worker, Service Worker, offline command와 Background Sync의 구현 결정은 프론트엔드 런타임 Capability 저장소 정합형 구현 결정 폐쇄 상세 설계가 정본이다. 본 문서의 해당 서술이 정본과 충돌하면 정본을 따른다.

1. 목적

이 문서는 도메인과 무관하게 다음을 바로 구현할 수 있는 기준을 제공한다.

  • typed route와 안전한 URL
  • session, permission, feature flag guard
  • lazy chunk의 loading/error/recovery
  • route 이동 시 focus, scroll, 취소, dirty form 처리
  • list, detail, form, status 등 공통 page template
  • page controller와 application input use case의 연결
  • 프론트엔드에서 반복 사용하는 설계 패턴

2. 현재 상태와 구현 기준

RP-04 이후 route runtime과 RP-06 page/form platform에는 다음 장점이 있다.

  • route registry가 path와 access policy를 소유한다.
  • contract에서 Data Router route object와 navigation을 생성한다.
  • runtime map이 route component를 lazy import하고 codec을 연결한다.
  • 앱 셸과 보호 route, not-found surface가 있다.
  • route heading focus와 비동기/render error boundary가 있다.
  • redirect loop와 chunk recovery가 bounded production call graph에 연결돼 있다.
  • src/presentation/templates가 standard/collection/detail/form/status slot, landmark와 responsive layout을 제공한다.
  • src/presentation/forms가 첫 오류 focus, error summary, 422 mapping, duplicate submit과 dirty route blocker를 소유한다.
  • reference feature의 list/detail/create/status route가 네 template variation을 production composition에서 실행한다.

platform route 계약, src/features/installed-feature-contracts.ts, src/presentation/routes/route-runtime.tsx의 완전성은 TypeScript와 registry negative fixture가 함께 검사한다. feature route의 codec은 그 route의 context route handle(codecs)에 실려 route와 함께 적재된다(15-01). params/search codec, loading/error surface, access, title, navigation, chunk ID는 src/presentation/routes/app-router.tsx에서 모두 소비된다. built Vite manifest의 dynamic entry는 release manifest route chunk map과 검증되며, ChunkRecoveryBoundary는 일반 render error와 chunk rejection을 분리한다.

route ID와 parsed input type은 route-contract.ts, parse/canonical URL 생성은 route-codecs.ts, React context/provider/hook은 route-input.tsx가 소유한다. router는 codec 결과를 provider에 넣고 lazy feature page는 좁은 useRouteInput()만 소비한다. 이 분리로 feature runtime이 자신을 load하는 app-router.tsx를 역참조하지 않으며, 같은 유형의 TypeScript 순환 의존은 architecture graph fixture가 거절한다.

template는 데이터를 가져오지 않는다. reference page controller가 route input과 application input을 query/form facade에 연결하고, template에는 render할 slot과 안전한 callback만 전달한다. 이 분리는 page-templates-own-layout-only dependency rule과 forbidden import fixture가 검증한다.

3. React Router mode 결정

React Router 공식 mode 설명과 Data Mode custom setup은 Declarative, Data, Framework Mode를 구분한다.

저장소에는 현재 React Router 7.18.1이 고정돼 있다. 구현 브랜치는 공식 문서의 동일 버전 API를 기준으로 하고 router version upgrade를 Data Mode 구조 변경과 같은 브랜치에 섞지 않는다. 위 공식 링크의 기본 표시 버전이 바뀌면 version selector를 7.18.1로 맞춰 확인한다.

mode 선택 조건 이 저장소에서의 판단
Declarative React composition과 외부 data layer가 route data를 소유 RP-04 이전 기준선
Data route object, blocker, scroll restoration, pending/navigation state가 필요 VD-03으로 채택하고 RP-04에서 구현
Framework route module, type-safe href, code splitting, SSR/static 전략을 framework가 소유 client-only skeleton 기본값으로는 범위가 큼

채택한 결정:

  • client-only SPA와 TanStack Query/application use case를 유지한다.
  • createBrowserRouter와 RouterProvider 기반 Data Mode를 사용한다.
  • Data Mode를 선택하는 이유는 route object, navigation blocker, scroll restoration, route error 경계를 일관되게 소유하기 위해서다. loader/action으로 서버 상태를 다시 소유하기 위해서가 아니다.
  • loader/action을 추가할 때는 TanStack Query/application input을 prefetch하거나 호출하는 한 가지 소유 경로만 사용한다.
  • 같은 데이터를 route loader와 TanStack Query가 각각 가져오지 않는다.
  • SSR/static generation을 선택하기 전에는 Framework Mode를 기본값으로 만들지 않는다.

결정 근거와 rollback 경계는 docs/architecture/decisions/VD-03-react-router-data-mode.md에 고정한다. Data Mode를 사용할 수 없는 프로젝트만 별도 ADR과 NavigationLifecycleAdapter를 구현한다.

4. route 계약과 runtime map

4.1 두 종류의 레지스트리

직렬화 가능한 contract와 React implementation을 분리한다.

export const routeContracts = {
  home: {
    id: "home",
    path: "/",
    access: "public",
    navigation: "primary",
    titleKey: "route.home.title",
    loadingSurface: "page",
    errorSurface: "page",
    chunkId: "home",
  },
  resourceDetail: {
    id: "resourceDetail",
    path: "/examples/resources/:resourceId",
    access: "authenticated",
    navigation: "hidden",
    titleKey: "route.resourceDetail.title",
    loadingSurface: "detail",
    errorSurface: "detail",
    chunkId: "reference-resource-detail",
  },
} as const satisfies RouteContractRegistry;
export const routeRuntime = {
  home: {
    Component: lazy(() => import("../pages/home-page")),
    paramsCodec: emptyParamsCodec,
    searchCodec: emptySearchCodec,
  },
  resourceDetail: {
    Component: lazy(() => import("../features/resources/resource-detail-page")),
    paramsCodec: resourceDetailParamsCodec,
    searchCodec: resourceDetailSearchCodec,
  },
} satisfies Record<RouteId, RouteRuntime>;

요구 사항:

  • contract key와 id가 다르면 typecheck 실패
  • contract에는 함수, component, schema instance처럼 직렬화 불가능한 값을 넣지 않음
  • runtime map에는 실제 lazy component와 codec/guard만 둠
  • contract의 모든 route가 runtime에 있고 runtime의 모든 key가 contract에 있음
  • navigation은 contract에서 파생
  • build chunk manifest와 chunkId 대응을 검증
  • public runtime config나 server가 route component 이름을 임의 지정할 수 없음

4.2 params와 search codec

URL은 외부 입력이다. page에서 useParams() 결과를 cast하지 않는다.

const resourceDetailParamsSchema = z.object({
  resourceId: z.string().trim().min(1).max(100),
});

const resourceListSearchSchema = z.object({
  q: z.string().trim().max(100).catch(""),
  page: z.coerce.number().int().min(1).catch(1),
  sort: z.enum(["updated-desc", "name-asc"]).catch("updated-desc"),
});

path params와 search params는 입력 형태와 serialization 규칙이 다르므로 같은 interface로 뭉치지 않는다. 각각 parse와 serialize를 제공한다.

interface PathParamsCodec<T> {
  parse(
    input: Readonly<Record<string, string | undefined>>,
  ): Result<T, RouteInputFailure>;
  serialize(value: T): Readonly<Record<string, string>>;
}

interface SearchParamsCodec<T> {
  parse(input: URLSearchParams): Result<T, RouteInputFailure>;
  serialize(value: T): URLSearchParams;
}

규칙:

  • route input parse 실패와 backend 404를 구분한다.
  • 알 수 없는 search key를 보존할지 제거할지 route별로 선언한다.
  • default value를 URL에 항상 쓸지 생략할지 codec이 결정한다.
  • array/date/boolean encoding을 feature마다 다르게 만들지 않는다.
  • navigation link도 codec 기반 builder를 사용한다.
  • query key에는 parsed value만 사용한다.
  • 검색어·식별자를 telemetry에 기록하기 전에 sensitivity policy를 적용한다.

4.3 route object 생성

하나의 factory가 다음을 조합한다.

route contract
  + runtime component/codecs
  + access guard
  + feature flag guard
  + suspense surface
  + render/chunk error surface
  + title/focus/scroll behavior
  -> executable route object/tree

JSX에서 route별 <Route>를 다시 나열하지 않는다. nested layout이 필요한 경우 contract에 parent ID를 두고 cycle/orphan/duplicate path를 registry gate에서 검사한다.

5. guard와 권한

5.1 guard 순서

권장 순서:

  1. runtime/bootstrap readiness
  2. route 존재와 URL parse
  3. feature flag
  4. session readiness
  5. authentication
  6. coarse client permission hint
  7. route component
  8. server authorization result

client guard는 UX 최적화일 뿐 보안 경계가 아니다. API/BFF가 항상 최종 권한을 검사한다.

5.2 guard 결과

type GuardDecision =
  | { kind: "allow" }
  | { kind: "redirect"; to: SafeLocation; reason: RedirectReason }
  | { kind: "render"; surface: "auth-required" | "forbidden" | "not-found" };
  • redirect에는 origin route와 bounded return URL을 사용한다.
  • 외부 redirect는 allowlist를 거친다.
  • 동일한 route 쌍을 반복하는 redirect loop를 차단한다.
  • session이 아직 resolving이면 forbidden으로 단정하지 않는다.
  • server가 403을 반환하면 client claim을 신뢰해 화면을 계속 보여 주지 않는다.

6. navigation lifecycle

6.1 loading

loading surface를 route metadata에 연결한다.

surface 사용
shell 초기 앱 셸 진입
page 새로운 전체 페이지
collection table/list 구조 유지
detail metadata/content 구조 유지
form 필드 layout 구조 유지
inline 부분 action

cached data가 있으면 full-page skeleton으로 교체하지 않고 refreshing indicator를 사용한다. prefers-reduced-motion에서 skeleton animation을 줄인다.

6.2 error와 lazy chunk recovery

route error boundary는 다음을 구분한다.

  • render/programmer error
  • dynamic import/chunk load error
  • application AppFailure
  • URL parse failure
  • not found

chunk recovery 순서:

  1. 현재 build ID와 release manifest를 확인한다.
  2. 새 manifest가 확인되고 같은 build에 대해 reload하지 않았다면 한 번만 reload한다.
  3. 같은 failure가 반복되면 reload loop를 막는다.
  4. 안전한 support surface와 trace/build ID를 표시한다.
  5. recovery 결과를 redacted diagnostics에 기록한다.

지원 참조는 사용자가 문의할 때 말하는 값이고, 진단 이벤트에서 같은 값을 찾을 수 있다.

  • 라우트 렌더 실패: buildId:incidentId. 같은 incident ID가 ui.render.failed 진단의 correlation_id에 남는다(render-error-boundary.tsx의 newIncidentId, create-application.ts의 reportRenderFailure). 화면에는 "한 번 새로고침" 버튼이 있다(app-router.tsx의 RouteFailureSurface).
  • 복구하지 못한 청크 실패: 같은 형식이다. ChunkRecoveryBoundary의 onUnrecovered가 같은 ID로 ui.render.failed를 기록한다.
  • 조회 실패: AppFailure.requestId. HTTP 진단의 correlation_id와 같은 값이다 (async-surface.tsx의 TerminalErrorSurface).

custom fallback을 넘겨 retry/reset 기능을 잃지 않게 한다. boundary는 location.key 또는 route ID가 바뀌면 적절히 reset된다.

6.3 focus와 scroll

  • route 성공 후 main의 page heading에 programmatic focus
  • mouse 사용자가 불필요한 focus ring을 보지 않게 할 수는 있지만 keyboard focus indication을 전역으로 제거하지 않음
  • modal/drawer가 닫히면 opener에 focus 복원
  • backward/forward navigation은 저장한 scroll 복원. 복원은 브라우저가 하고, RouteLifecycle은 POP이 아닐 때만 top으로 보낸다(app-router.tsx). PageHeader의 heading focus는 preventScroll이라 복원된 위치를 옮기지 않는다
  • 새 primary route는 top으로 이동
  • hash target은 fixed header offset과 focus 가능 여부를 처리. 페이지가 그려진 뒤 PageHeader가 대상으로 스크롤하고, 대상이 focus 가능하면 대상에, 아니면 heading에 focus한다(page-header.tsx). header 높이는 html의 scroll-padding-top으로 뺀다(shell.css). 브라우저 검증은 tests/e2e/scroll-restoration.spec.ts
  • screen reader용 route title/live announcement는 중복 발표를 피함

6.4 취소와 dirty form

  • route 이동 시 진행 중 query signal을 취소한다.
  • mutation은 취소 안전성이 명확할 때만 취소한다.
  • dirty form blocker는 browser unload와 in-app navigation을 구분한다.
  • 성공 저장 후 blocker를 해제한 다음 이동한다.
  • autosave가 있는 form은 pending/failed 상태를 별도로 알린다.
  • confirm dialog는 공통 accessible primitive를 사용한다.

7. 페이지 템플릿

template은 데이터를 가져오거나 application을 호출하지 않는다. 슬롯, landmark, focus target, responsive layout, 상태 위치만 소유한다.

7.1 StandardPageTemplate

슬롯:

  • breadcrumb 또는 back link
  • title, description, status badge
  • primary/secondary actions
  • notices
  • content
  • contextual aside

작은 화면에서 action wrapping 순서와 heading hierarchy를 보장한다.

7.2 CollectionPageTemplate

슬롯과 상태:

  • title/actions
  • search/filter/sort toolbar
  • active filter summary와 reset
  • result count
  • table/list/card view
  • pagination 또는 load-more
  • initial loading, refreshing, empty-first-use, empty-filtered, error
  • bulk selection/action

URL이 filter, sort, page를 소유한다. template은 query 상태를 직접 읽지 않는다.

7.3 DetailPageTemplate

  • breadcrumb/back
  • title/status/actions
  • summary metadata
  • main sections
  • related/context aside
  • loading/not-found/forbidden/error
  • destructive action confirmation 위치

식별자가 바뀔 때 이전 entity 내용과 새 loading 상태를 혼동하지 않게 key/reset 정책을 명시한다.

7.4 FormPageTemplate

  • title/description
  • error summary
  • field groups
  • optional aside/help
  • sticky 또는 normal action bar
  • submit/cancel
  • submitting/saved/conflict/unavailable
  • dirty navigation confirmation

template은 특정 form vendor를 import하지 않는다.

7.5 StatusPageTemplate

다음 변형을 제공한다.

  • unauthenticated
  • forbidden
  • not found
  • unavailable
  • offline
  • maintenance
  • unexpected

각 변형은 heading, 짧은 설명, 안전한 primary/secondary action, 선택적 trace ID를 갖는다. raw stack/response를 표시하지 않는다.

7.6 선택 template

다음은 project 필요가 있을 때 추가한다.

  • SettingsPageTemplate
  • DashboardGridTemplate
  • SplitPaneTemplate
  • WizardTemplate
  • FullScreenTaskTemplate

8. page controller 패턴

page를 세 부분으로 나눈다.

route adapter
  parses URL and guard context
      ↓
controller hook
  invokes application query/mutation and maps UI events
      ↓
page view
  renders template and design-system components

예:

export function ResourceListRoute() {
  const input = useRouteInput();
  return <ResourceListController input={input} />;
}

function ResourceListController({ input }: ResourceListControllerProps) {
  const controller = useResourceListController(input);
  return <ResourceListPage controller={controller} />;
}

router의 parse/invalid-route boundary가 성공한 ParsedRouteInput만 provider에 넣고, page controller는 그 context를 바로 읽는다. 따라서 controller hook은 조건부로 호출되지 않는다.

controller가 소유하는 것:

  • parsed route input을 application input으로 변환
  • query/mutation state
  • pagination/filter/navigation event
  • retry/refresh/action callbacks
  • view model projection

view가 소유하는 것:

  • semantic markup
  • template/component 조립
  • focus target
  • 사용자의 local-only interaction

controller가 소유하지 않는 것:

  • HTTP URL 조립
  • credential
  • transport DTO parse
  • 도메인 invariant
  • raw vendor SDK

9. 권장 패턴 카탈로그

패턴 적용 위치 쓰는 이유 오용
Ports and Adapters application 외부 경계 정책과 기술 교체 분리 모든 작은 UI library에 port 생성
Command/Query application input 읽기/변경 의도와 정책 분리 CQRS 인프라를 필요 없이 도입
Gateway output port 외부 데이터 capability 표현 get/post 범용 HTTP를 application에 노출
Anti-Corruption Mapper outbound feature adapter DTO 변화가 core로 전파되지 않게 함 단순 object spread로 타입만 바꿈
Result 예상 실패 실패 종류와 처리 경로를 닫음 programmer error까지 모두 Result로 숨김
Controller/View inbound React data lifecycle과 markup 분리 거대한 hook 하나에 모든 feature 로직 집중
Strategy retry/cache/auth recovery 정책 교체와 테스트 가능성 설정 한 줄도 interface로 과도 추상화
Observer/External Store session/theme/realtime React 외부 소유 상태 구독 server state를 다시 external store에 복제
State Machine 복잡한 workflow 유효 전이와 보상 명시 단순 modal open에 도입
Headless/Compound Component 복합 UI behavior와 style/slot 분리 vendor primitive를 제품 전역에 직접 노출
Adapter Facade icon/form/i18n vendor React inbound 내부 vendor 교체 경계 application port로 승격
Page Template 반복 layout/state 접근성과 반응형 구조 재사용 data fetching을 template에 포함
Registry + Runtime Map route/operation/event 선언과 실행 완전성 모든 설정을 하나의 거대 전역 파일에 집중

RP-08 이후 route contract의 title/navigation 필드는 fallback metadata이며 실제 document title, navigation, loading/error/access surface는 route.<ROUTE_ID>.title|navigation typed catalog key를 해석한다. route params, search, backend message를 translation key로 조립하지 않는다. locale 변경은 현재 route를 재요청하거나 query key를 바꾸지 않고 document title과 화면 copy만 다시 렌더링한다.

패턴은 추상화 파일만 만든 것으로 완료되지 않는다. reference usage, negative architecture test, 실패 상태 test가 있어야 제공된 패턴으로 본다.

10. 새 route/page 추가 recipe

  1. feature public 경계와 route ID를 정한다.
  2. serializable route contract를 등록한다.
  3. params/search Zod schema와 bidirectional codec을 작성한다.
  4. safe URL builder를 export한다.
  5. lazy page module과 runtime map entry를 추가한다.
  6. session/permission/flag guard를 선언한다.
  7. 적절한 page template을 선택한다.
  8. controller hook을 application input API에 연결한다.
  9. loading, empty, refreshing, error, auth, forbidden, not-found를 결정한다.
  10. title/message key, focus, scroll, chunk ID를 연결한다.
  11. 다음 검증을 추가한다.
    • contract/runtime map type completeness
    • codec round-trip/property cases
    • guard decision unit
    • page component state
    • query/mutation integration
    • keyboard/focus/axe
    • direct URL, back/forward, refresh E2E
    • chunk failure recovery가 필요한 route의 E2E
  12. registry, type, architecture, component, integration, E2E gate를 실행한다.

11. 금지 패턴

  • page 안에서 raw fetch, storage, auth SDK, telemetry SDK 호출
  • useParams()/URLSearchParams 값을 cast만 하고 사용
  • route contract와 JSX route tree를 각각 수동 관리
  • protected route를 server authorization 대체 수단으로 취급
  • 모든 실패를 redirect 또는 full-page error로 처리
  • query data가 있는데 background error 때문에 내용을 제거
  • chunk load error에서 제한 없는 location.reload
  • route heading focus outline을 CSS로 무조건 제거
  • template이 data fetching 또는 feature-specific copy를 소유
  • generic BasePage prop 하나에 모든 layout variation을 boolean으로 추가

12. 완료 기준

  • 모든 route ID가 contract와 runtime map에서 compile-time 완전성을 가진다.
  • params/search parse와 URL serialize가 같은 codec을 사용한다.
  • route metadata가 loading/error/chunk/title/navigation 행동에 실제 연결된다.
  • redirect와 chunk reload loop가 차단된다.
  • route 이동 시 query 취소, focus, scroll, dirty policy가 검증된다.
  • collection/detail/form/status reference page가 template을 사용한다.
  • page view가 application input 외의 외부 capability를 직접 호출하지 않는다.
  • 새 route recipe와 테스트만으로 별도 라우터 내부 지식 없이 기능을 추가할 수 있다.