🔌 @dammers/use-signalr

Fully-typed, reusable SignalR provider + hooks for React — driven entirely by your contract.

const { SignalRProvider, useSignalRInvoke } = createSignalRClient({
  hubs: {
    "/hubs/chat": {
      methods: { SendMessage: method<[roomId: string, message: string]>() },
    },
  },
});

One factory call gives you a provider and a set of hooks, every one of them typed against your hub contract — inferred straight from the config, no separately hand-written contract type. Event args, method args and return values are all inferred.

---

✨ Features

• 🌐 Many hubs, one provider. Manage any number of hubs side by side — each gets its own connection, status, config and lifecycle. List them as keys; the hooks take the hub you want.
• 🧠 Fully typed, contract inferred from config. Declare each hub's events/methods once with event()/method() — no hand-written contract type, no declare module, no globals. Event args, method args and return values are all inferred.
• 🔇 No "No client method found" warnings, by construction. Every event you declare is automatically pre-bound to a no-op handler at connection build time — nothing to opt into, nothing that can drift from the contract.
• ⚙️ Per-hub & global config. Set defaults once, override anything per hub: reconnect strategy, retries, transport, logging, lazy behavior.
• ♻️ Auto-reconnect. Built-in: true, a custom delay array, or your own retry policy. Plus a connect-retry budget for the first connect.
• 🔁 Invoke retry. Opt-in per call, idempotent-safe, with jittered backoff and smart retriable-vs-business-error detection.
• 💤 Lazy hubs. Connect on first use, disconnect (after a grace period) on last unmount. Ref-counted and StrictMode-safe.
• 🟢 Live per-hub status. Subscribe to a hub's connection state; components re-render only when that hub changes.
• 🔄 Reconnect hooks. Run a callback after a hub reconnects — e.g. refetch state that went stale.
• 🔑 Auth via props. Pass baseUrl + accessTokenFactory (gate with the optional enabled); the token is re-read on every negotiate, so rotation needs no rebuild.
• 🪶 Zero runtime deps. Only peer deps: react, react-dom, @microsoft/signalr.

📦 Install

npm i @dammers/use-signalr @microsoft/signalr

Peer deps: react ≥ 19, react-dom ≥ 19, @microsoft/signalr ≥ 8 (tested against 8–10). React 19 is required — the library uses the use hook and JSX context providers.

🚀 Usage

1. Define your contract and create the client

Your app contract isn't hand-written — it's inferred from the config. The keys of config.hubs declare the hubs; each hub's events (what the server pushes to you) and methods (what you invoke) are declared inline using the event() and method() markers.

// signalr.ts
import { createSignalRClient, event, method } from "@dammers/use-signalr";

export const {
  SignalRProvider,
  useSignalR,
  useSignalREffect,
  useSignalRInvoke,
  useSignalRSend,
  useSignalRTeardown,
  useHubStatus,
  useOnReconnected,
  useHubConsumer,
} = createSignalRClient({
  hubs: {
    "/hubs/chat": {
      events: {
        ReceiveMessage: event<[user: string, message: string]>(),
      },
      methods: {
        SendMessage: method<[roomId: string, message: string]>(),
        JoinRoom: method<[roomId: string], { success: boolean }>(),
      },
      // per-hub config also goes here (see "Per-hub config")
    },
  },
  // global defaults (all optional):
  // lazy: false, reconnect: true, maxConnectRetries: 2, logLevel: LogLevel.Information
});

event<Args>() takes the handler's argument tuple; method<Args, Return>() takes the argument tuple and the resolved return type (defaults to void if omitted). Neither returns anything meaningful at runtime — they're phantom-typed markers whose only job is to carry the types for inference. createSignalRClient is called with no explicit generic: its type is inferred from the config object you pass.

2. Mount the provider with your auth

The provider takes no hubs prop — it already knows them from the config.

import { SignalRProvider } from "./signalr";

<SignalRProvider
  baseUrl={serverUrl} // e.g. "https://api.example.com"
  accessTokenFactory={() => getAccessToken()} // sync or async; read on every (re)negotiate
  enabled={isAuthenticated} // optional, default true; false -> stops + clears all connections
  connectionKey={accessToken} // optional: forces reconnect when it changes (re-login)
  onError={(hub, err) => toast.error(`Connection to ${hub} failed`)}
  onStatusChange={(hub, status) => {
    if (status === "reconnecting") toast.warning(`Reconnecting to ${hub}…`);
    if (status === "reconnected") toast.success(`Reconnected to ${hub}`);
  }}
>
  <App />
</SignalRProvider>;

3. Use the hooks — everything below is fully typed

// 📥 Listen to a server event — args inferred from the contract
useSignalREffect("/hubs/chat", "ReceiveMessage", (user, message) => {
  console.log(user, message);
});

// 📤 Invoke a server method — args + return inferred, waits for connection
const sendMessage = useSignalRInvoke("/hubs/chat", "SendMessage");
await sendMessage(roomId, "hello"); // typed params, Promise<void>

// 🏹 Typed fire-and-forget — no connect-wait, dropped if the hub isn't connected.
// Stable across renders, so it's safe to capture in an unmount cleanup.
const send = useSignalRSend("/hubs/chat", "SendMessage");
await send(roomId, "bye"); // typed args; Promise<boolean> (true = dispatched)

// 🚪 Reliable teardown — for a method called in an effect cleanup. Survives
// unmount, queues if the hub is still connecting (instead of dropping), holds a
// lazy hub open until it flushes. Best-effort: Promise<boolean> (true = dispatched).
const leaveRoom = useSignalRTeardown("/hubs/chat", "LeaveRoomAsync");
useEffect(() => {
  joinRoom(roomId);
  return () => {
    leaveRoom(roomId);
  }; // lands even mid-connect or on unmount
}, [roomId, joinRoom, leaveRoom]);

// 🟢 Live connection status (re-renders only when THIS hub's status changes)
const status = useHubStatus("/hubs/chat"); // "connecting" | "connected" | "reconnecting" | ...

// 🔄 Re-sync after a reconnect (e.g. refetch a query)
useOnReconnected("/hubs/chat", () => refetchMessages());

// ⚓ Keep a lazy hub connected for this component's lifetime without subscribing
useHubConsumer("/hubs/chat");

// 🛠️ Last resort: the raw HubConnection (prefer the typed hooks above)
const { getConnection } = useSignalR();
getConnection("/hubs/chat")?.send("SendMessage", roomId, "bye");

⚙️ Per-hub config

Each value in config.hubs overrides the global defaults for that hub, alongside its events/methods declarations:

createSignalRClient({
  hubs: {
    "/hubs/chat": {
      events: { ReceiveMessage: event<[user: string, message: string]>() },
      methods: { SendMessage: method<[roomId: string, message: string]>() },
    },
    "/hubs/presence": {
      events: { UserOnline: event<[userId: string]>() },
      lazy: true, // connect only when first used
      graceMs: 5000, // wait 5s after last consumer before disconnect
      reconnect: [0, 2000, 10000, 30000], // custom retry delays (ms)
      maxConnectRetries: 5,
      transport: HttpTransportType.WebSockets,
      skipNegotiation: true,
    },
  },
  lazy: false, // global default for all hubs
  reconnect: true, // true | false | number[] | IRetryPolicy
  maxConnectRetries: 2,
});

🔇 No "No client method found" warnings — by construction

@microsoft/signalr logs a warning whenever the server pushes an event with no registered handler — which happens for any event no mounted component currently subscribes to via useSignalREffect. Every event you declare with event() in a hub's config is automatically pre-bound to a no-op handler at connection build time (before start()) — there's no separate opt-in list to keep in sync, and nothing to forget: if it's in the contract, it's pre-bound. Real handlers registered later via useSignalREffect (or connection.on) still receive events normally — SignalR fans out to every registered handler. This has no effect on connection lifecycle (lazy/eager behavior is unchanged).

💤 Lazy hubs

With lazy: true, a hub connects only when the first component using it mounts (any hook for that hub) and disconnects graceMs after the last one unmounts. Ref-counted and StrictMode-safe. Default is eager.

🔁 Invoke retry

useSignalRInvoke fails fast by default (retries: 0, rethrows the raw server error). Opt in only for idempotent methods — a retried invoke is at-least-once:

const undo = useSignalRInvoke("/hubs/flow", "UndoAsync", {
  retries: 2, // retry RETRIABLE failures (transport drops, 5xx, timeouts)
  timeout: 15000, // per-attempt deadline
  backoff: [250, 1000, 3000], // or (attempt) => ms; capped 30s, jittered
});

Business errors (a HubException thrown while still connected) are never retried.

🚪 send vs invoke vs teardown — which call to use

The three "call the server" hooks differ in how they wait, what they return, and what happens on unmount. Pick by intent:

	useSignalRInvoke	useSignalRSend	useSignalRTeardown
Waits for connection	yes (up to timeout)	no	yes (up to timeout)
Not connected yet	waits, then invokes	drops (resolves false)	queues, flushes on connect
Returns	the method's typed result	boolean (dispatched?)	boolean (dispatched?)
On unmount	aborts in-flight call¹	unaffected (reads conn at call time)	survives (runs detached)
Holds a lazy hub open	while mounted	while mounted	until the flush completes
Use for	request/response you need the result of	high-frequency loss-OK signals (typing, cursor)	one-shot teardown that must land

¹ Only a mid-backoff retry is actually cancelled; pass { keepAliveOnUnmount: true } to keep it alive.

Reliable join/leave (session pattern)

A common pattern: join a session on mount, leave it in the effect cleanup.

const joinRoom = useSignalRInvoke("/hubs/chat", "JoinRoomAsync");
const leaveRoom = useSignalRTeardown("/hubs/chat", "LeaveRoomAsync");

useEffect(() => {
  joinRoom(roomId);
  return () => {
    leaveRoom(roomId);
  };
}, [roomId, joinRoom, leaveRoom]);

A plain useSignalRInvoke or useSignalRSend makes the leave unreliable:

• useSignalRInvoke aborts in-flight calls on unmount — a leave issued in cleanup can be cancelled before it reaches the server.
• useSignalRSend drops silently if the hub isn't Connected — so a leave that races a still-connecting socket (StrictMode's first mount, fast route switches) is lost.

useSignalRTeardown fixes both. It:

• survives the calling component's unmount (runs detached, never aborted),
• queues while connecting — waits up to timeout (default 10s) for the hub, then sends, instead of dropping,
• holds a lazy hub open until the flush completes, even if the unmounting component was its last consumer.

It's best-effort fire-and-forget: resolves true once dispatched, false if the hub never connected in time; it never throws. Under StrictMode's mount→cleanup→mount, the intermediate teardown does land (then the remount re-runs setup) — so the server is never left in a stale joined state, at the cost of one extra round-trip.

Already use useSignalRInvoke for your leave and only need it not to be aborted on unmount? Pass { keepAliveOnUnmount: true }. That covers the abort half but not the still-connecting race — for that, use useSignalRTeardown.

📚 API

Export	What it does
createSignalRClient(config)	Returns the Provider + hooks, typed against the contract inferred from config. Config keys declare the hubs; no explicit generic needed.
event<Args>()	Declares a server-pushed event inside a hub's events; Args is the handler's argument tuple.
method<Args, Return?>()	Declares an invocable server method inside a hub's methods; Args is the argument tuple, Return the resolved return type (default void).
<SignalRProvider>	Builds/starts connections, retries, auto-reconnects, exposes them via context. No hubs prop.
useSignalREffect(hub, event, handler)	Subscribe to a server event for the component lifetime.
useSignalRInvoke(hub, method, opts?)	Typed request/response invoker; waits for the connection, returns the method's result. Optional retry/backoff/timeout; keepAliveOnUnmount to not abort on unmount.
useSignalRSend(hub, method)	Typed fire-and-forget sender; drops if not connected. For high-frequency loss-OK signals. Safe in unmount cleanups.
useSignalRTeardown(hub, method, opts?)	Reliable teardown sender for a method called in cleanup: survives unmount, queues while connecting (instead of dropping), holds a lazy hub open until flushed.
useHubStatus(hub)	Live connection status; re-renders only when that hub changes.
useOnReconnected(hub, cb)	Run cb after the hub reconnects (e.g. refetch).
useHubConsumer(hub)	Keep a lazy hub connected for the component's lifetime without subscribing.
useSignalR()	Last-resort raw context: getConnection, isHubConnected, getStatus.

Provider props

baseUrl, accessTokenFactory (required); enabled (optional, default true), connectionKey, onStatusChange, onError (optional). Connection behavior (lazy, reconnect, maxConnectRetries, logLevel, per-hub overrides) lives in the config passed to createSignalRClient, not on the provider.

📝 Notes

• The provider rebuilds connections when baseUrl, enabled, or connectionKey change. Token rotation alone does not rebuild — accessTokenFactory is re-read on every negotiate.
• accessTokenFactory and the on* callbacks are read through refs, so passing fresh closures each render is fine — no reconnect storm.

🤝 Contributing

Setup, scripts and workflow live in CONTRIBUTING.md.

📄 License

MIT © DammersCode