Router 이벤트

TanStack Router는 router.subscribe를 통해 라우터 수명 주기 이벤트를 노출합니다. 분석, 외부 상태 초기화, 탐색 후 DOM 의존 로직 실행과 같은 명령형 사이드 이펙트에 유용합니다.

기본 사용법

router.subscribe는 이벤트 이름과 리스너를 받은 다음 구독 취소 함수를 반환합니다.

const unsubscribe = router.subscribe('onResolved', (event) => {
  console.info('Navigation finished:', event.toLocation.href)
})

// Later, clean up the listener
unsubscribe()

사용 시점

router.subscribe는 렌더링을 구동하지 않고 탐색을 관찰해야 하는 명령형 통합에 적합합니다.

분석 및 페이지뷰 추적
외부 캐시 또는 뮤테이션 상태 초기화
탐색 시간과 전환 로깅
라우트 렌더링 후 DOM 의존 로직 실행

반응형 UI 업데이트가 필요하다면 수동으로 구독하는 대신 useRouterState, useSearch, useParams와 같은 프레임워크 훅을 사용하는 것이 좋습니다.

사용 가능한 이벤트

TanStack Router는 다음 수명 주기 이벤트를 발생시킵니다.

onBeforeNavigate - 탐색이 시작되기 직전
onBeforeLoad - 라우트 로딩이 시작되기 전
onLoad - 다음 위치가 커밋되고 라우트 매치가 로드된 후
onBeforeRouteMount - 로딩이 끝난 후, 라우트 컴포넌트가 마운트되기 직전
onResolved - 탐색이 완전히 해결된 후
onRendered - 라우트가 렌더링된 후

전체 이벤트 페이로드 타입은 RouterEvents 타입을 참고하세요.

일반적인 이벤트 흐름

일반적인 탐색에서 이벤트는 보통 다음 순서로 흐릅니다.

onBeforeNavigate
onBeforeLoad
onLoad
onBeforeRouteMount
onResolved
onRendered

일반적으로 모든 이벤트가 필요한 것은 아닙니다. 다음을 기준으로 삼을 수 있습니다.

탐색 시작을 관찰하려면 onBeforeNavigate 또는 onBeforeLoad를 사용합니다.
탐색이 끝난 후 분석과 정리를 수행하려면 onResolved를 사용합니다.
DOM 의존 작업에는 onRendered를 사용합니다.

이벤트 페이로드

탐색 이벤트는 변경된 내용을 설명하는 위치 변경 메타데이터를 받습니다.

const unsubscribe = router.subscribe('onBeforeNavigate', (event) => {
  console.info({
    from: event.fromLocation?.href,
    to: event.toLocation.href,
    pathChanged: event.pathChanged,
    hrefChanged: event.hrefChanged,
    hashChanged: event.hashChanged,
  })
})

몇 가지 유용한 세부 사항은 다음과 같습니다.

초기 로드에서는 fromLocation이 undefined일 수 있습니다.
pathChanged는 pathname이 변경되었는지 나타냅니다.
hrefChanged에는 pathname, search, hash 변경이 포함됩니다.
hashChanged는 hash만 변경된 탐색을 구분하는 데 유용합니다.

일반적인 패턴

페이지뷰 추적

onResolved는 탐색이 끝난 후 발생하므로 분석에 적합한 기본값입니다.

const unsubscribe = router.subscribe('onResolved', ({ toLocation }) => {
  analytics.track('page_view', {
    path: toLocation.pathname,
    href: toLocation.href,
  })
})

외부 뮤테이션 상태 지우기

키가 지정된 뮤테이션 상태를 지원하지 않는 뮤테이션 라이브러리를 사용한다면 탐색 후 상태를 지웁니다.

const unsubscribe = router.subscribe('onResolved', ({ pathChanged }) => {
  if (pathChanged) {
    mutationCache.clear()
  }
})

DOM 의존 로직 실행

새 라우트 콘텐츠가 이미 DOM에 있어야 사이드 이펙트를 실행할 수 있다면 onRendered를 사용합니다.

const unsubscribe = router.subscribe('onRendered', ({ toLocation }) => {
  focusPageHeading(toLocation.pathname)
})

컴포넌트에서 구독 취소

컴포넌트 또는 프레임워크 이펙트에서 구독한다면 정리 함수에서 항상 구독 취소 함수를 반환해야 컴포넌트가 언마운트될 때 리스너가 제거됩니다.

기본 사용법​

사용 시점​

사용 가능한 이벤트​

일반적인 이벤트 흐름​

이벤트 페이로드​

일반적인 패턴​

페이지뷰 추적​

외부 뮤테이션 상태 지우기​

DOM 의존 로직 실행​

컴포넌트에서 구독 취소​

관련 API​