Next.js encountered URL data outside of Suspense

증상

Client-side navigation 중 Server Component가 <Suspense> 경계 밖에서 params 또는 searchParams를 읽으면 개발 오버레이에 Next.js encountered URL data outside of Suspense가 표시될 수 있습니다. 원문은 이 URL 데이터가 특정 URL에 종속되어 공유 App Shell에서 재사용될 수 없다고 설명합니다.

확인

1. 해당 경로를 next dev로 로드하거나 해당 경로로 이동합니다.
2. 개발 오버레이에 Next.js encountered URL data outside of Suspense가 표시되는지 확인합니다.
3. 오류 오버레이가 가리키는 컴포넌트의 파일 경로와 줄 번호에서 params 또는 searchParams를 <Suspense> 경계 밖에서 읽는지 확인합니다.
4. 빌드 결과를 확인하는 경우 next build의 출력이 간략하면 next build --debug-prerender로 전체 사용자 코드 스택을 확인합니다. 특정 경로만 반복 확인하려면 next build --debug-build-paths /dashboard /settings처럼 경로를 지정합니다.

해결

URL에 따라 달라지는 내용이 이동 이후 렌더링되어도 되는 경우에는 해당 읽기를 <Suspense> 경계 안의 자식 컴포넌트로 옮깁니다. params 또는 searchParams Promise를 자식에게 전달하고 경계 안에서 읽으면 나머지 경로는 공유 prefetch에 남을 수 있습니다.

<Suspense fallback={<ResultsSkeleton />}>  <Results searchParams={searchParams} /></Suspense>

경로가 URL 데이터를 트리 상위에서 읽어야 하며 공유 App Shell을 제공할 수 없는 경우에는 해당 page 또는 layout에 다음을 추가할 수 있습니다.

export const instant = false

이 설정을 사용하면 해당 segment가 navigation마다 렌더링되며 즉시 navigation 검사를 받지 않습니다. 원문은 가능한 경우 <Suspense> 경계를 사용하는 방법을 우선 선택하라고 안내합니다.

수정 후 확인

경로로 다시 이동해 개발 오버레이에 해당 insight가 더 이상 표시되지 않는지 확인합니다. 페이지가 의미 있는 UI를 즉시 표시하고, <Suspense> fallback이 이후 스트리밍되는 영역만 덮는지 확인합니다.

설정 또는 코드 변경 전 현재 값을 기록하고 가능한 경우 백업 또는 내보내기를 준비합니다. 여러 항목을 동시에 변경하지 말고 한 번에 하나만 변경합니다. 오류가 발생하면 기록한 이전 값으로 복구합니다.