Guide

WebSockets

H3 has built-in support for cross platform WebSocket and SSE.

H3 natively supports runtime agnostic WebSocket API using CrossWS.

You can define WebSocket handlers in your existing Event Handlers to define multiple websocket handlers, dynamically matched with your same route definitions!
Read more in WebSocket in MDN.
Read more in CrossWS.
WebSockets support is currently experimental and available in nightly channel.

Usage

Example

You can use npx listhen --ws -w websocket.ts to run this example
websocket.ts
import { createApp, defineEventHandler, defineWebSocketHandler } from "h3";

export const app = createApp();

app.use(
  defineEventHandler(async () => await import("./_ws").then((m) => m.default)),
);

app.use(
  "/_ws",
  defineWebSocketHandler({
    open(peer) {
      peer.send({ user: "server", message: `Welcome ${peer}!` });
      peer.publish("chat", { user: "server", message: `${peer} joined!` });
      peer.subscribe("chat");
    },
    message(peer, message) {
      if (message.text().includes("ping")) {
        peer.send({ user: "server", message: "pong" });
      } else {
        const msg = {
          user: peer.toString(),
          message: message.toString(),
        };
        peer.send(msg); // echo
        peer.publish("chat", msg);
      }
    },
    close(peer) {
      peer.publish("chat", { user: "server", message: `${peer} left!` });
    },
  }),
);

Server Sent Events (SSE)

As an alternative to WebSockets, you can use Server-sent events.

H3 has a built-in API to create server-sent events using createEventStream(event) utility.

SSE support is currently experimental and available in nightly channel.

Example

server-sent-events.ts
import { createApp, createRouter, eventHandler, createEventStream } from "h3";

export const app = createApp();

const router = createRouter();
app.use(router);

router.get(
  "/",
  eventHandler((event) => {
    const eventStream = createEventStream(event);

    // Send a message every second
    const interval = setInterval(async () => {
      await eventStream.push("Hello world");
    }, 1000);

    // cleanup the interval when the connection is terminated or the writer is closed
    eventStream.onClosed(() => {
      clearInterval(interval);
    });

    return eventStream.send();
  }),
);