WebSocket support in Bun
Bun supports WebSockets through the standard new WebSocket() constructor for clients and through Bun.serve() for server-side WebSocket handling.
bun apis/websockets
22 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
WebSocket event handlers
WebSocket handlers are declared once on the server and reused across all connections. The websocket object supports: message(ws, message) called when a message is received; open(ws) called when a socket is opened; close(ws, code, reason) called when a socket is closed; drain(ws) called when the socket is ready to receive more data; error(ws, error) called when an error occurs.
ServerWebSocket.send() method
Send messages to clients using ws.send(). Supports string, ArrayBuffer, Uint8Array (or other TypedArray), DataView, and Blob types. Returns a number: -1 means enqueued with backpressure, 0 means dropped due to connection issue, 1+ is the number of bytes sent. Optionally pass true as second argument to compress: ws.send(message, true).
WebSocket upgrade headers
Attach custom headers to the 101 Switching Protocols response by passing a headers object to server.upgrade(). Example: server.upgrade(req, { headers: { "Set-Cookie": "SessionId=xyz" } }).
WebSocket contextual data
Attach contextual data to a WebSocket by passing a data object to server.upgrade(req, { data: {...} }). Access this data in handlers via ws.data. To type ws.data in TypeScript, add a data property to the websocket handler object with the type annotation: data: {} as MyDataType.
WebSocket pub/sub API
ServerWebSocket includes publish-subscribe for topic-based broadcasting. Use ws.subscribe(topic) to subscribe to a topic, ws.unsubscribe(topic) to unsubscribe, ws.publish(topic, message) to publish to all other subscribers (excluding self), and server.publish(topic, message) to publish to all subscribers including the caller. Check subscriptions with ws.subscriptions and ws.isSubscribed(topic).
WebSocket compression settings
Enable per-message compression with perMessageDeflate: true. For fine control, use perMessageDeflate: { compress, decompress } where each can be a boolean or Compressor type. Compressor options are: "disable", "shared", "dedicated", or memory sizes: "3KB", "4KB", "8KB", "16KB", "32KB", "64KB", "128KB", "256KB".
WebSocket idle timeout and payload limits
By default, Bun closes idle WebSocket connections after 120 seconds. Set idleTimeout (in seconds) to customize. Default maximum message payload is 16 MB (16777216 bytes). Set maxPayloadLength to customize.
Bun.serve websocket handler options reference
The websocket parameter accepts: message (required handler), open, close, error, drain (optional handlers); maxPayloadLength (default: 16777216), idleTimeout (default: 120 seconds), backpressureLimit (default: 16777216), closeOnBackpressureLimit (default: false), sendPings (default: true), publishToSelf (default: false), perMessageDeflate (boolean or object with compress/decompress).
ServerWebSocket properties and methods reference
ServerWebSocket has: data (contextual data), readyState (connection state), remoteAddress (client IP), subscriptions (array of subscribed topics), send(message, compress?), close(code?, reason?), subscribe(topic), unsubscribe(topic), publish(topic, message), isSubscribed(topic), cork(cb).
Server.publish() return value
Server.publish(topic, data, compress?) returns a number representing the operation result, similar to ServerWebSocket.send().
WebSocket server with Bun.serve
Use Bun.serve() to start a WebSocket server. In the fetch handler, call server.upgrade(req) to upgrade an incoming request to a WebSocket connection. Return undefined on successful upgrade, or return a Response if upgrade fails. Declare WebSocket handlers in the websocket parameter.
WebSocket client event listeners
WebSocket clients support addEventListener with event types: "message", "open", "close", "error".
Bun WebSocket performance benchmark
Bun's WebSocket implementation handles approximately 700,000 messages per second with 16 clients on Linux x64 (Bun v0.2.1), compared to approximately 100,000 messages per second with Node.js + ws library. Bun's WebSocket is built on uWebSockets.
Server.upgrade() method signature
server.upgrade(req, options?) where options can include headers (HeadersInit) and data (any). Returns boolean: true if upgrade succeeded, false if it failed.
Server.pendingWebSockets property
The Server instance exposes a pendingWebSockets property indicating the number of pending WebSocket connections.
WebSocket upgrade request cookies
Cookies set on the page are sent with the WebSocket upgrade request and are available via req.headers in the fetch handler. Parse them to identify users and set contextual data accordingly.
ServerWebSocket.cork() method
Use ws.cork(cb) to batch multiple operations together. Pass a callback that will execute with the socket in a corked state, batching sends for better performance.
WebSocket server example with pub/sub and chat
Example server that upgrades requests to WebSocket at /chat path, attaches username to ws.data, subscribes to "the-group-chat" topic on open, publishes messages to all other subscribers when messages arrive, and unsubscribes on close. Messages include username prefix. The server publishes join/leave notifications.
WebSocket client connection example
const socket = new WebSocket("ws://localhost:3000"); socket.addEventListener("message", event => { console.log(event.data); });
WebSocket send examples
ws.send("Hello world"); ws.send(response.arrayBuffer()); ws.send(new Uint8Array([1, 2, 3])); ws.send(new Blob(["binary"]));
WebSocket client in Bun
Bun implements the WebSocket class. Create a client with new WebSocket(url) or new WebSocket(url, subprotocols). Bun-specific extension: pass a headers object as second argument for custom headers: new WebSocket("ws://localhost:3000", { headers: {...} }). This does not work in browsers.