use-server-sent-event

useServerSentEvent

English

React-хук для работы с Server-Sent Events (SSE).

Требования

• React 18 или новее;
• браузер с поддержкой EventSource;
• Bun нужен только для запуска локального demo.

Установка

npm install use-server-sent-event

Использование

import { useServerSentEvent } from 'use-server-sent-event';

type ServerMessage = {
  id: string;
  value: number;
};

function Messages() {
  const { data, error, isConnected } = useServerSentEvent<ServerMessage>(
    '/api/events',
    undefined,
  );

  if (error) {
    return <p>Ошибка SSE: {error.message}</p>;
  }

  return (
    <section>
      <p>Статус: {isConnected ? 'Подключено' : 'Отключено'}</p>
      <pre>{JSON.stringify(data, null, 2)}</pre>
    </section>
  );
}

По умолчанию данные каждого события разбираются через JSON.parse. Числа являются допустимым JSON, а для plain text можно передать собственный parser.

API

useServerSentEvent<T>(url, initialState?, options?)

Существующая сигнатура с двумя аргументами поддерживается. Третий аргумент необязателен.

Опции:

• parse — функция преобразования raw payload в T; по умолчанию JSON.parse;
• eventName — имя SSE-события, по умолчанию message;
• withCredentials — передавать cookies при cross-origin подключении;
• reconnect — сохранять нативное переподключение EventSource, по умолчанию true;
• resetOnUrlChange — сбрасывать data и error при смене URL, по умолчанию true;
• enabled — создавать подключение только при true, по умолчанию true.

Возвращаемые значения:

• data — последние данные или undefined;
• error — последняя ошибка подключения или парсинга;
• isConnected — true после события open.

Нативный EventSource не позволяет передавать произвольные HTTP-заголовки. Для авторизации используйте cookies, query-параметры или другой транспорт.

SSR

На сервере подключение не создаётся. Во время SSR хук возвращает initialState, error: null и isConnected: false. Передавайте одинаковый initialState на сервере и клиенте, чтобы избежать hydration mismatch.

Demo и проверки

Запуск полного demo из корня репозитория:

npm run demo

Откройте http://localhost:3000 для vanilla-интерфейса или http://localhost:3000/react для React-интерфейса, который использует собранный dist/index.js.

Проверка перед публикацией:

npm run verify

Подробности находятся в examples/README.md.

Лицензия

MIT. См. LICENSE.