feat: Add enabled prop to useWebSocket hook for conditional connection control.

packages/partysocket/src/react.ts

@@ -45,7 +45,7 @@ export default function usePartySocket(options: UsePartySocketOptions) {
       ])
   });
 
-  useAttachWebSocketEventHandlers(socket, options);
+  useAttachWebSocketEventHandlers(socket!, options);
 
   return socket;
 }

packages/partysocket/src/use-handlers.ts

@@ -11,7 +11,7 @@ export type EventHandlerOptions = {
 
 /** Attaches event handlers to a WebSocket in a React Lifecycle-friendly way */
 export const useAttachWebSocketEventHandlers = (
-  socket: WebSocket,
+  socket: WebSocket | null,
   options: EventHandlerOptions
 ) => {
   const handlersRef = useRef(options);
@@ -27,16 +27,16 @@ export const useAttachWebSocketEventHandlers = (
     const onError: EventHandlerOptions["onError"] = (event) =>
       handlersRef.current?.onError?.(event);
 
-    socket.addEventListener("open", onOpen);
-    socket.addEventListener("close", onClose);
-    socket.addEventListener("error", onError);
-    socket.addEventListener("message", onMessage);
+    socket?.addEventListener("open", onOpen);
+    socket?.addEventListener("close", onClose);
+    socket?.addEventListener("error", onError);
+    socket?.addEventListener("message", onMessage);
 
     return () => {
-      socket.removeEventListener("open", onOpen);
-      socket.removeEventListener("close", onClose);
-      socket.removeEventListener("error", onError);
-      socket.removeEventListener("message", onMessage);
+      socket?.removeEventListener("open", onOpen);
+      socket?.removeEventListener("close", onClose);
+      socket?.removeEventListener("error", onError);
+      socket?.removeEventListener("message", onMessage);
     };
   }, [socket]);
 };

packages/partysocket/src/use-socket.ts

@@ -28,7 +28,7 @@ export function useStableSocket<T extends WebSocket, TOpts extends Options>({
   createSocketMemoKey: createOptionsMemoKey
 }: {
   options: TOpts;
-  createSocket: (options: TOpts) => T;
+  createSocket: (options: TOpts) => T | null;
   createSocketMemoKey: (options: TOpts) => string;
 }) {
   // ensure we only reconnect when necessary
@@ -39,7 +39,7 @@ export function useStableSocket<T extends WebSocket, TOpts extends Options>({
   }, [shouldReconnect]);
 
   // this is the socket we return
-  const [socket, setSocket] = useState<T>(() =>
+  const [socket, setSocket] = useState<T | null>(() =>
     // only connect on first mount
     createSocket({ ...socketOptions, startClosed: true })
   );
@@ -68,13 +68,13 @@ export function useStableSocket<T extends WebSocket, TOpts extends Options>({
     } else {
       // if this is the first time we are running the hook, connect...
       if (!socketInitializedRef.current && socketOptions.startClosed !== true) {
-        socket.reconnect();
+        socket?.reconnect();
       }
       // track initialized socket so we know not to do it again
       socketInitializedRef.current = socket;
       // close the old socket the next time the socket changes or we unmount
       return () => {
-        socket.close();
+        socket?.close();
       };
     }
   }, [socket, socketOptions]);

packages/partysocket/src/use-ws.ts

@@ -8,17 +8,31 @@ import WebSocket from "./ws";
 import type { EventHandlerOptions } from "./use-handlers";
 import type { Options, ProtocolsProvider, UrlProvider } from "./ws";
 
-type UseWebSocketOptions = Options & EventHandlerOptions;
+type UseWebSocketOptions = Options &
+  EventHandlerOptions & {
+    /**
+     * Whether to enable WebSocket connection (if `false`, connection won't be established. Defaults to `true`)
+     */
+    enabled?: boolean;
+  };
 
 // A React hook that wraps PartySocket
 export default function useWebSocket(
   url: UrlProvider,
   protocols?: ProtocolsProvider,
   options: UseWebSocketOptions = {}
 ) {
+  const { enabled = true, ...restOptions } = options;
+
   const socket = useStableSocket({
-    options,
-    createSocket: (options) => new WebSocket(url, protocols, options),
+    options: restOptions,
+    createSocket: (options) => {
+      if (!enabled) {
+        return null;
+      }
+
+      return new WebSocket(url, protocols, options);
+    },
     createSocketMemoKey: (options) =>
       JSON.stringify([
         // will reconnect if url or protocols are specified as a string.
@@ -29,7 +43,7 @@ export default function useWebSocket(
       ])
   });
 
-  useAttachWebSocketEventHandlers(socket, options);
+  useAttachWebSocketEventHandlers(socket!, restOptions);
 
   return socket;
 }