useSyncExternalStore

Сигнатура — три функции: subscribe, getSnapshot и (для SSR) getServerSnapshot. subscribe(cb) регистрирует колбэк, который React вызывает при каждом изменении стора, и возвращает функцию отписки. getSnapshot() синхронно возвращает текущее значение. getServerSnapshot() возвращает значение для рендеринга на сервере и первой клиентской гидратации, где браузерных API не существует.

"use client";
import { useSyncExternalStore } from "react";

function useOnlineStatus(): boolean {
  return useSyncExternalStore(
    // subscribe: соединяем стор -> React, возвращаем очистку
    (onStoreChange) => {
      window.addEventListener("online", onStoreChange);
      window.addEventListener("offline", onStoreChange);
      return () => {
        window.removeEventListener("online", onStoreChange);
        window.removeEventListener("offline", onStoreChange);
      };
    },
    () => navigator.onLine,        // getSnapshot (клиент)
    () => true,                    // getServerSnapshot (на сервере navigator нет)
  );
}

React подписывается один раз, читает снимок на каждом рендере и перерисовывает компонент, когда срабатывает onStoreChange. Никакого эффекта, никакого зеркального useState, никакого устаревшего первого рендера.

Почему не useEffect + useState? Потому что это зеркало рвётся при конкурентном рендеринге и устаревает на первой отрисовке. Эффект выполняется после первого коммита, так что первый рендер показывает то значение по умолчанию, которым ты его засеял, а не настоящее. Хуже того: поскольку значение живёт в твоей собственной копии состояния, конкурентный рендер, начавшийся до обновления, может закоммитить старое значение, пока другая часть дерева коммитит новое, — один и тот же стор прочитан как два разных. useSyncExternalStore читает снимок синхронно во время рендера и форсирует согласованное, неразорванное чтение по всему коммиту.

// ❌ рефлекс: подписка-в-эффекте, зеркало в состоянии
function useOnlineStatusBad() {
  const [online, setOnline] = useState(navigator.onLine); // на сервере тоже падает
  useEffect(() => {
    const on = () => setOnline(navigator.onLine);
    window.addEventListener("online", on);
    window.addEventListener("offline", on);
    return () => {
      window.removeEventListener("online", on);
      window.removeEventListener("offline", on);
    };
  }, []);
  return online; // устаревшее до запуска эффекта; может рваться при конкурентных рендерах
}

Именно поэтому собственная документация React перечисляет это в разделе «возможно, эффект тебе не нужен»: подписка на внешний стор — в точности тот случай, где зеркало-через-эффект — неправильный инструмент, а этот хук — правильный.

getSnapshot ОБЯЗАН возвращать стабильную ссылку для неизменившихся данных — свежий объект на каждый вызов — это бесконечный цикл рендера. После каждого рендера React вызывает getSnapshot и сравнивает результат с предыдущим через Object.is. Если это новое значение, React предполагает, что стор изменился, и перерисовывается — что снова вызывает getSnapshot — что возвращает ещё один новый объект — и так вечно. Лечение — возвращать ту же ссылку, пока сами данные действительно не изменятся (кешировать их в сторе), либо выбрать примитив.

// ❌ новая идентичность массива на каждый вызов -> Object.is всегда false -> цикл
const todos = useSyncExternalStore(store.subscribe, () => store.todos.filter(t => !t.done));

// ✅ возвращаем кешированную ссылку; пересчитываем только при мутации стора
const todos = useSyncExternalStore(store.subscribe, store.getVisibleTodos);
// где getVisibleTodos мемоизирует и выдаёт новый массив только при изменении todos

// ✅ или читаем примитив, который сравнивается по значению
const count = useSyncExternalStore(store.subscribe, () => store.todos.length);

Если тебе действительно нужен производный объект на каждый рендер, выводи его снаружи хука через useMemo из стабильного снимка — никогда внутри getSnapshot. (useSyncExternalStoreWithSelector из use-sync-external-store/shim/with-selector существует ровно для случая «выбрать и сравнить».)

Пропусти getServerSnapshot в любом SSR/RSC-клиентском приложении — и обрушишь серверный рендер. Во время серверного рендеринга и первого прохода гидратации нет ни window, ни navigator, так что getSnapshot бросает исключение (navigator is not defined) — или, если не бросает, серверный HTML и первый клиентский рендер расходятся, и ты получаешь рассогласование гидратации. getServerSnapshot поставляет безопасное, детерминированное значение для сервера и гидратации; затем React после монтирования перечитывает getSnapshot и обновляется, если настоящее значение отличается.

return useSyncExternalStore(
  subscribe,
  () => navigator.onLine,  // клиентский снимок — только в браузере
  () => true,              // серверный снимок — считаем, что онлайн во время SSR/гидратации
);

В Next.js App Router этот хук выполняется только в "use client"-компоненте, но клиентские компоненты всё равно рендерятся на сервере для исходного HTML, так что в этом мире третий аргумент не опционален — это разница между чистой гидратацией и падением в рантайме на первом запросе.