WebSockets

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!

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();
  }),
);

Edit this page (some contents are generated with automd from source)

Router

Split your application using routes.

Nightly Builds