useSyncExternalStore API와 매개변수

useSyncExternalStore는 최대 세 가지 인수인 구독 함수, getSnapshot, 선택적 getServerSnapshot을 받습니다. 이 인수들은 함께 React에 변경 사항을 감지하는 방법과 현재 값을 읽는 방법을 알려 줍니다.

각 인수를 이해하는 것이 필수적입니다. 이 훅을 사용할 때 인수의 작은 실수가 버그의 가장 흔한 원인이기 때문입니다.

구독 함수는 React에서 콜백을 받아 저장소에 등록해야 하며, 저장소가 변경될 때마다 해당 콜백이 실행되도록 해야 합니다. 또한 React가 정리할 때 호출할 구독 해제 함수를 반환해야 합니다.

React는 이를 통해 스냅샷을 다시 읽어야 할 시점을 파악하므로, 구독 함수는 변경 알림을 연결하고 해제하는 역할만 담당합니다.

getSnapshot은 저장소의 현재 값을 반환합니다. React는 렌더링 중 상태를 읽기 위해 이를 호출하고, 알림을 받은 후 값이 변경되었는지 감지하기 위해 다시 호출합니다.

중요한 점은 기반 데이터가 변경되지 않았을 때 참조가 안정적인 결과를 반환해야 한다는 것입니다. 매번 새 객체를 만드는 대신 동일한 참조를 반환해야 합니다.

선택적 getServerSnapshot은 서버 측 렌더링과 초기 수화 과정에서 사용되는 값을 제공합니다. 브라우저 전용 getSnapshot은 서버에 존재하지 않는 API에 의존할 수 있기 때문에 필요합니다.

이를 제공하면 서버가 클라이언트에서 처음 생성할 결과와 일치하는 적절한 값을 렌더링하므로 수화 불일치를 방지할 수 있습니다.

이 훅은 현재 스냅샷 값을 반환하며, 이를 다른 상태 값과 마찬가지로 컴포넌트에서 직접 사용합니다. 저장소가 변경되면 React가 다시 렌더링하고 훅은 업데이트된 스냅샷을 반환합니다.

기준 데이터가 전적으로 React 외부에 존재하더라도 컴포넌트에서는 반응형 상태를 읽는 것처럼 느껴집니다.

getSnapshot은 동기적으로 실행되고 현재 저장소 상태에서만 계산된 값을 반환해야 합니다. 비동기 작업을 수행하거나 동일한 기반 데이터에 대해 서로 다른 결과를 만들어서는 안 됩니다.

React는 이를 반복해서 호출하고 결과를 비교하므로, 내부의 비결정적 동작이나 부수 효과가 잘못된 동작을 일으킬 수 있습니다.

불변 상태를 보유한 저장소에서는 데이터가 변경될 때만 현재 상태 객체의 참조가 바뀌므로 getSnapshot을 쉽게 구현할 수 있습니다. 해당 참조를 반환하면 안정적인 비교를 별도 작업 없이 수행할 수 있습니다.

이것이 불변 업데이트 패턴이 이 훅과 잘 맞는 이유입니다. 데이터가 같으면 참조도 같으므로 React가 불필요한 재렌더링을 건너뜁니다.

흔한 오류는 getSnapshot을 호출할 때마다 완전히 새로운 객체나 배열을 반환하는 것입니다. 예를 들어 함수 내부에서 데이터를 변환하거나 필터링하는 경우가 이에 해당합니다. React는 매번 새 참조를 보고 값이 변경되었다고 판단합니다.

그러면 무한 재렌더링이나 경고가 발생합니다. 해결 방법은 파생된 값을 캐시하고 원본 데이터가 실제로 변경될 때까지 동일한 참조를 반환하는 것입니다.

루프를 피하려면 getSnapshot 외부에서 파생 데이터를 계산하거나 메모이제이션하여 함수가 캐시된 참조를 반환하게 합니다. 많은 라이브러리가 사용하는 선택자 방식은 정확히 이러한 안정성을 관리하기 위한 것입니다.

핵심 규칙은 저장소 데이터가 변경되지 않았다면 getSnapshot을 두 번 호출해도 정확히 같은 참조를 반환해야 한다는 것입니다.

실제로는 리스너를 추가하고 제거하는 구독 함수, 안정적인 현재 값을 읽는 getSnapshot, 그리고 SSR 환경에서는 서버에서 안전한 값을 반환하는 getServerSnapshot을 작성합니다.

이 세 가지가 올바르게 구현되면 번거로운 설정을 최소화하면서 외부 저장소를 일관되고 동시성에 안전하게 읽을 수 있습니다.

getSnapshot의 역할을 파악합니다.

이 훅은 구독 함수, getSnapshot, 선택적인 getServerSnapshot을 받습니다. 구독 함수는 리스너를 연결하고 구독 해제 함수를 반환하며, getSnapshot은 현재 값을 동기적으로 읽고 참조가 안정적이어야 합니다. getServerSnapshot은 SSR에서 안전하게 사용할 값을 제공합니다.

대표적인 실수는 호출할 때마다 새 객체를 반환하여 무한 루프를 일으키는 것입니다. 파생된 값을 캐시하여 변경되지 않은 데이터가 같은 참조를 반환하도록 하세요.