@noverachat/sdk-react

🇰🇷 한국어

React hooks/bindings for NoveraChat — a thin layer over @noverachat/sdk-web (the headless NoveraChat / Room core). It does NOT reimplement chat logic and it does NOT ship chat UI — this package is only the glue: a lifecycle-managed provider and hooks that turn the SDK's events into React state.

Tip: inject a cacheStore in the client options and useMessages renders the last known history instantly on cold start (snapshot cache) — zero screen-code changes.

Install

npm i @noverachat/sdk-react @noverachat/sdk-web react

react >= 18 is a peer dependency (uses useSyncExternalStore).

Quick start

import {
  NoveraChatProvider,
  useMessages,
  useTyping,
} from "@noverachat/sdk-react";

function App() {
  return (
    <NoveraChatProvider
      options={{
        appId: "app_9f8k2x",
        endpoint: "https://chat.example.com",
        tokenProvider: async () => fetchJwt(),
      }}
    >
      <ChatScreen roomId="room_123" />
    </NoveraChatProvider>
  );
}

function ChatScreen({ roomId }: { roomId: string }) {
  const { messages, hasMore, store } = useMessages(roomId);
  const { isAnyoneTyping, setTyping } = useTyping(roomId);

  return (
    <>
      {hasMore && <button onClick={() => store.loadMore()}>older…</button>}
      {messages.map((m) => (
        <div key={m.id}>
          {m.isDeleted ? "(deleted)" : m.content}
          {m.status === "sending" && " ⏳"}
          {m.status === "failed" && " ⚠️"}
        </div>
      ))}
      {isAnyoneTyping && <span>typing…</span>}
      <input
        onChange={() => setTyping(true)}
        onKeyDown={(e) => {
          if (e.key !== "Enter") return;
          store.send(e.currentTarget.value);
          e.currentTarget.value = "";
        }}
      />
    </>
  );
}

API

| Export | What it is | |---|---| | NoveraChatProvider / useNoveraChat() | Creates a NoveraChat, runs connect()/disconnect() over the mount lifecycle; the hook reads it anywhere below. Options are read once — remount with a new key to reconnect differently. | | useRoom(roomId) | The Room facade, for direct SDK calls the hooks don't cover (members, announcements, invites, moderation, …). | | useMessages(roomId, opts?) | Live message list (ChatMessage[], oldest first) + hasMore + readWatermarks, plus the backing RoomStore for actions: send, sendFile (with upload progress), edit, delete, toggleReaction, markRead, loadMore, search, isReadBy, readCount. Sends are optimistic — a sending bubble flips to sent on ack or failed on error. | | useTyping(roomId, opts?) | Who's typing (auto-expires after timeoutMs, default 5s) + setTyping to broadcast your own state. | | useUnread(opts?) | Account-wide unread badge: total, per-room summary, refresh(), optional refreshIntervalMs polling. | | useRoomList(opts?) | Live chat-room list (채팅 탭): previews, unread badges, most-recent-first ordering. New messages bump rooms to the top; membership events trigger a debounced reload. Actions: markRead, hideRoom, unhideRoom. | | useMemberList(roomId) | Live member list — roles, operators, activeMemberIds (for read-receipt math), presence dots updated in place. | | useRoomFiles(roomId, opts?) | Paginated media/file grid (파일함·앨범), newest first: items, media (images/videos only), hasMore, store.loadMore() / store.refresh(). | | useRoomSettings(roomId) | Room-settings actions: setMuted / setPushTrigger, invite-link CRUD, join-request inbox (approve/reject), leave / clearHistory / deleteMyMessages, operator moderation (freeze, setPublic, muteMember, …). | | ChatMessage | Uniform view model over history (REST), live (WS) and optimistic messages. | | RoomStore | The framework-agnostic store behind useMessages, usable outside hooks (tests, non-React glue). |

Everything from @noverachat/sdk-web is re-exported, so a single import gets you NoveraChat, Room, message/event types, etc.

Documentation

React-specific guides are on the NoveraChat docs site (source under docs/) — start with build a chat screen.

| Section | Contents | |---|---| | Getting started | Install + wire a chat screen | | Guides | State & lifecycle · chat-room list · read receipts · files & media · room settings screen | | Reference | Hooks & stores API |

Chat behavior — auth, connection, messaging, rooms, push, errors — is documented in @noverachat/sdk-web, not duplicated here.

Notes

• The read watermark (markRead) is debounced inside the core SDK; the store flushes it automatically when the tab is hidden/closed and on unmount, so unread counts stay correct across devices.
• StrictMode-safe: subscriptions attach/detach cleanly across the simulated double mount, and the initial history load is guarded against duplication.