React

@arkosjs/react-websockets is the reference framework binding for @arkosjs/websockets-client — the one that's actually been used and tested. If you're building a binding for another framework, this is the API shape to match as closely as your framework's idioms allow.

Setup

import { Manager } from "socket.io-client";
import { ArkosSocketProvider } from "@arkosjs/react-websockets";

const manager = new Manager("http://localhost:3000", {
  auth: { token: "your-auth-token" },
});

function App() {
  return (
    <ArkosSocketProvider manager={manager}>
      <Chat />
    </ArkosSocketProvider>
  );
}

One provider at the root — every useGateway() call below it shares the same underlying WebsocketClient.

useGateway

One hook per namespace:

function Chat() {
  const chat = useGateway("/chat");

  useEffect(() => {
    return chat.on("receive_message", (data) => {
      setMessages((m) => [...m, data]);
    });
  }, [chat]);

  return <div>{chat.status}</div>;
}

• chat.on(event, handler) — subscribes, cleans up automatically on unmount.
• chat.status — reactive: "connected" | "reconnecting" | "disconnected".
• chat.user — reactive: the user object populated when the server emits "authenticated", or null.

useEmit

For events you emit from user actions, with loading/error state handled for you:

function MessageInput({ room }: { room: string }) {
  const chat = useGateway("/chat");
  const sendMessage = chat.useEmit("send_message");

  return (
    <button
      disabled={sendMessage.loading}
      onClick={() =>
        sendMessage.emit({ room, content: "hello" }, { ack: true })
      }
    >
      Send
    </button>
  );
}

• sendMessage.emit(data, options?) — { ack: true } waits for server acknowledgement; omit it for fire-and-forget.
• sendMessage.loading — reactive, true while an acked emit is in flight.
• sendMessage.error — reactive, set if the emit fails or the server returns { success: false }.
• sendMessage.lastEmittedAt — reactive timestamp of the last emit call.
• sendMessage.reset() — clears error/loading manually.

Cleanup

Handled for you — ArkosSocketProvider destroys the underlying client when it unmounts, and every chat.on() subscription cleans up when its component unmounts.