Skip to main content
Version: Next

wasp/client/webSocket

React hooks for using your app's WebSocket server from the client. Only available if your app sets the webSocket field of the app spec.

All the hooks are typed with the events and payloads you defined on the server, in your webSocketFn (see WebSocketDefinition). Your editor autocompletes the events and payloads, and you get type errors if you make a mistake. If you don't type your webSocketFn, any event name is allowed.

See Using the WebSocket on the client for a complete chat page example.

Type Aliases​

ClientToServerPayload​

ClientToServerPayload<Event> = Parameters<ClientToServerEvents[Event]>[0]

The payload type of an event the client sends to the server.

Type Parameters​

Event​

Event extends keyof ClientToServerEvents

The name of the event, as defined on the server.

Example​

import { type ClientToServerPayload } from "wasp/client/webSocket";

const message: ClientToServerPayload<"chatMessage"> = "Hello!";

ServerToClientPayload​

ServerToClientPayload<Event> = Parameters<ServerToClientEvents[Event]>[0]

The payload type of an event the server sends to the client.

Type Parameters​

Event​

Event extends keyof ServerToClientEvents

The name of the event, as defined on the server.

Example​

import { type ServerToClientPayload } from "wasp/client/webSocket";

function logMessage(message: ServerToClientPayload<"chatMessage">) {
  console.log(message);
}

Functions​

useSocket()​

useSocket(): object

Gives you access to the WebSocket connection.

Wasp automatically connects to the WebSocket server when the app loads, so you don't need to call socket.connect() or socket.disconnect(). If you set autoConnect: false in the webSocket field of the app spec, call them as needed.

All components using useSocket share the same underlying socket. When the user logs in or out, Wasp reconnects it if it's connected, so the server sees the new session.

Returns​

isConnected​

isConnected: boolean

Whether the socket is connected. Useful for showing the connection status.

socket​

socket: Socket<ServerToClientEvents, ClientToServerEvents>

The Socket.IO client Socket, for sending and receiving events.

Example​

import { useSocket } from "wasp/client/webSocket";

export const ChatPage = () => {
  const { socket, isConnected } = useSocket();

  function sayHello() {
    socket.emit("chatMessage", "Hello!");
  }
  // ...
};

useSocketListener()​

useSocketListener<Event>(event, handler): void

Registers a handler for an event the server sends. It unregisters the handler when the component unmounts.

Type Parameters​

Event​

Event extends string | number

Parameters​

event​

Event

The name of the event, as defined on the server.

handler​

ServerToClientEvents[Event]

The function to call with the event's payload.

Returns​

void

Example​

import { useState } from "react";
import {
  useSocketListener,
  type ServerToClientPayload,
} from "wasp/client/webSocket";

export const ChatPage = () => {
  const [messages, setMessages] = useState<
    ServerToClientPayload<"chatMessage">[]
  >([]);

  useSocketListener("chatMessage", (message) => {
    setMessages((priorMessages) => [message, ...priorMessages]);
  });
  // ...
};

Referenced Types​

ClientToServerEvents​

The events the client sends to the server, as a map from event names to listener functions.

In your app, it's the ClientToServerEvents type argument of the WebSocketDefinition you type your webSocketFn with.

Extends​

  • EventsMap

Indexable​

[event: string]: any

ServerToClientEvents​

The events the server sends to the client, as a map from event names to listener functions.

In your app, it's the ServerToClientEvents type argument of the WebSocketDefinition you type your webSocketFn with.

Extends​

  • EventsMap

Indexable​

[event: string]: any