The following server, built with Bun.serve, upgrades every incoming request to a WebSocket connection in the fetch handler. The socket handlers are declared in the websocket parameter.
server.ts
Bun.serve({ fetch(req, server) { // upgrade the request to a WebSocket if (server.upgrade(req)) { return; // do not return a Response } return new Response("Upgrade failed", { status: 500 }); }, websocket: {}, // handlers});
Bun supports these WebSocket event handlers:
server.ts
Bun.serve({ fetch(req, server) {}, // upgrade logic websocket: { message(ws, message) {}, // a message is received open(ws) {}, // a socket is opened close(ws, code, message) {}, // a socket is closed drain(ws) {}, // the socket is ready to receive more data },});
An API designed for speed
In Bun, handlers are declared once per server, instead of per socket.You pass a single WebSocketHandler object to Bun.serve() with methods for open, message, close, drain, and error. This is different from the client-side WebSocket class, which extends EventTarget (onmessage, onopen, onclose).Clients tend to have few socket connections open, so an event-based API makes sense there.But servers tend to have many socket connections open, which means:
Time spent adding/removing event listeners for each connection adds up
Extra memory spent on storing references to callback functions for each connection
Usually, people create new functions for each connection, which also means more memory
Reusing one handler object across every connection avoids both costs.
The first argument to each handler is the ServerWebSocket instance handling the event. The ServerWebSocket class is a fast, Bun-native implementation of WebSocket with some additional features.
server.ts
Bun.serve({ fetch(req, server) {}, // upgrade logic websocket: { message(ws, message) { ws.send(message); // echo back the message }, },});
Once the upgrade succeeds, Bun sends a 101 Switching Protocols response per the spec. To attach additional headers to this Response, pass them to server.upgrade().
Attach contextual data to a new WebSocket in the .upgrade() call. It is available on the ws.data property inside the WebSocket handlers.To strongly type ws.data, add a data property to the websocket handler object. This types ws.data across all lifecycle hooks.
server.ts
type WebSocketData = { createdAt: number; channelId: string; authToken: string;};Bun.serve({ fetch(req, server) { const cookies = new Bun.CookieMap(req.headers.get("cookie")!); server.upgrade(req, { // this object must conform to WebSocketData data: { createdAt: Date.now(), channelId: new URL(req.url).searchParams.get("channelId"), authToken: cookies.get("X-Token"), }, }); return undefined; }, websocket: { // TypeScript: specify the type of ws.data like this data: {} as WebSocketData, // handler called when a message is received async message(ws, message) { // ws.data is now properly typed as WebSocketData const user = getUserFromToken(ws.data.authToken); await saveMessageToDatabase({ channel: ws.data.channelId, message: String(message), userId: user.id, }); }, },});
Previously, you could specify the type of ws.data with a type parameter on Bun.serve, like Bun.serve<MyData>({...}). This pattern was removed due to a limitation in TypeScript in favor of the data property.
To connect to this server from the browser, create a new WebSocket.
browser.js
const socket = new WebSocket("ws://localhost:3000/chat");socket.addEventListener("message", event => { console.log(event.data);});
Identifying usersCookies set on the page are sent with the WebSocket upgrade request and available on req.headers in the fetch handler. Parse them to identify the connecting user and set data accordingly.
Bun’s ServerWebSocket includes a native publish-subscribe API for topic-based broadcasting. Individual sockets can .subscribe() to a topic (specified with a string identifier) and .publish() messages to all other subscribers to that topic (excluding itself). This topic-based broadcast API is similar to MQTT and Redis Pub/Sub.
server.ts
const server = Bun.serve({ fetch(req, server) { const url = new URL(req.url); if (url.pathname === "/chat") { console.log(`upgrade!`); const username = getUsernameFromReq(req); const success = server.upgrade(req, { data: { username } }); return success ? undefined : new Response("WebSocket upgrade error", { status: 400 }); } return new Response("Hello world"); }, websocket: { // TypeScript: specify the type of ws.data like this data: {} as { username: string }, open(ws) { const msg = `${ws.data.username} has entered the chat`; ws.subscribe("the-group-chat"); server.publish("the-group-chat", msg); }, message(ws, message) { // this is a group chat // so the server re-broadcasts incoming message to everyone server.publish("the-group-chat", `${ws.data.username}: ${message}`); // inspect current subscriptions console.log(ws.subscriptions); // ["the-group-chat"] }, close(ws) { const msg = `${ws.data.username} has left the chat`; ws.unsubscribe("the-group-chat"); server.publish("the-group-chat", msg); }, },});console.log(`Listening on ${server.hostname}:${server.port}`);
Calling .publish(data) sends the message to all subscribers of a topic except the socket that called .publish(). To send a message to all subscribers of a topic, use the .publish() method on the Server instance.
const server = Bun.serve({ websocket: { // ... },});// listen for some external eventserver.publish("the-group-chat", "Hello world");
Bun implements the WebSocket class. To create a WebSocket client that connects to a ws:// or wss:// server, create an instance of WebSocket, as you would in the browser.
const socket = new WebSocket("ws://localhost:3000");// With subprotocol negotiationconst socket2 = new WebSocket("ws://localhost:3000", ["soap", "wamp"]);
In browsers, cookies set on the page are sent with the WebSocket upgrade request. This is a standard feature of the WebSocket API.In Bun, you can also set custom headers directly in the constructor. This is a Bun-specific extension of the WebSocket standard. It does not work in browsers.
server.ts