API и параметры useSyncExternalStore

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.

Классическая ошибка — возвращать новый объект при каждом вызове, что приводит к бесконечным циклам. Кэшируйте производные значения, чтобы неизменившимся данным соответствовала та же ссылка.