디버깅 및 트러블슈팅

next-nexus는 개발 중 동작을 이해하는 데 도움이 되는 상세한 로깅 시스템을 포함하고 있습니다.

디버그 로그 활성화하기

상세 로그를 활성화하려면, .env.local 파일에 다음 변수를 추가하세요:

NEXT_PUBLIC_NEXUS_DEBUG=true

이 플래그가 있으면, next-nexus는 요청, 캐시 상호작용, 하이드레이션에 대한 정보를 브라우저의 개발자 콘솔에 출력합니다.

로그 이벤트 이해하기

요청 이벤트 (Request Events)

• START: 요청이 시작되었습니다.
• SUCCESS: 요청이 성공적으로 완료되었습니다.
• ERROR: 요청이 실패했습니다.
• TIMEOUT: 타임아웃으로 요청이 중단되었습니다.

캐시 이벤트 (Cache Events)

• HIT: 클라이언트 캐시에서 신선한(fresh) 항목을 찾았습니다.
• HIT-STALE: 클라이언트 캐시에서 만료된(stale) 항목을 찾았습니다.
• MISS: 클라이언트 캐시에서 항목을 찾지 못했습니다.
• SET: 캐시에 항목이 추가되었습니다.
• UPDATE: 캐시의 기존 항목이 업데이트되었습니다.
• DELETE: 캐시에서 항목이 제거되었습니다.

하이드레이션 & 위임 이벤트 (Hydration & Delegation Events)

• HYDRATE: 서버 렌더링 데이터로 클라이언트 캐시가 하이드레이션되었습니다.
• DELEGATE: NexusRenderer가 신선한 캐시 항목으로 인해 렌더링을 클라이언트에 위임했습니다.
• SKIP: 서버가 클라이언트에 이미 동일한 버전(ETag 일치)이 있어 해당 키의 하이드레이션을 건너뛰었습니다.
• MATCH: 서버가 클라이언트의 캐시 메타데이터에서 일치하는 항목을 찾았습니다.

일반적인 트러블슈팅 시나리오

하이드레이션이 작동하지 않을 때

• 경계 확인: 페이지나 레이아웃이 NexusHydrationBoundary 또는 withNexusHydrationBoundary로 감싸져 있는지 확인하세요.
• NexusRuntime 확인: 루트 레이아웃에 <NexusRuntime />이 있는지 확인하세요.
• definition 확인: 서버(nexus용)와 클라이언트(useNexusQuery용)에서 정확히 동일한 definition 객체(메서드, 엔드포인트, 태그 등 포함)를 사용해야 합니다. 조금이라도 다르면 캐시 키 불일치가 발생합니다.

캐시된 헤더가 누락되었을 때

• cachedHeaders 확인: 클라이언트에서 읽으려는 헤더 이름이 definition의 client.cachedHeaders 배열에 포함되어 있는지 확인하세요.