Working with WebSockets

WebSocket events are consumed through the socketSdk from @/api/sdk. Like the HTTP SDK, all events and payloads are typed from the backend definitions.

Setup

The socket SDK is created in src/api/sdk.ts:

import { createSocketSdk } from "@hyper-fetch/sockets";
import type { WsSocketSdk } from "@hype-stack/backend";

import { socket } from "./client";

export const socketSdk = createSocketSdk<typeof socket, WsSocketSdk>(socket);

Listening for events

Use useListener from @hyper-fetch/react to subscribe to server-pushed events:

import { useListener } from "@hyper-fetch/react";
import { socketSdk } from "@/api/sdk";

function NotificationBell() {
  const listener = useListener(socketSdk.notification.new.$listener);

  listener.onEvent(({ data: notification }) => {
    toast.info(notification.title);
  });

  return <BellIcon />;
}

Emitting events

Use useEmitter for client-to-server events:

import { useEmitter } from "@hyper-fetch/react";
import { socketSdk } from "@/api/sdk";

function MarkRead({ notificationId }: { notificationId: string }) {
  const { emit } = useEmitter(socketSdk.notification["mark-read"].$emitter);

  return (
    <button onClick={() => emit({ data: { notificationId } })}>
      Mark as read
    </button>
  );
}

Important rules

• Always use socketSdk directly. Don't create intermediate re-export files or alias variables for socket events.
• Import payload types from @hype-stack/backend when you need them explicitly (e.g., WsNotificationPayload).
• Never use raw useEffect + .listen() for socket subscriptions. The useListener hook handles cleanup and re-subscription automatically.
• New backend socket events appear on socketSdk automatically through the type bridge.