Bun.Server TypeScript interface | API Reference | Bun

HTTP & HTTPS Server

To start the server, see serve

For performance, Bun pre-allocates most of the data for 2048 concurrent requests. That means starting a new server allocates about 500 KB of memory. Try to avoid starting and stopping the server often (unless it's a new instance of bun).

Powered by a fork of uWebSockets. Thank you @alexhultman.

Is the server running in development mode?

In development mode, Bun.serve() returns rendered error messages with stack traces instead of a generic 500 error. This makes debugging easier, but development mode shouldn't be used in production or you will risk leaking sensitive information.

The hostname the server is listening on. Does not include the port.

This will be undefined when the server is listening on a unix socket.

"localhost"

An identifier of the server instance

When bun is started with the --hot flag, this ID is used to hot reload the server without interrupting pending requests or websockets.

When bun is not started with the --hot flag, this ID is currently unused.

How many requests are in-flight right now?

How many ServerWebSockets are in-flight right now?

The port the server is listening on.

This will be undefined when the server is listening on a unix socket.

3000

The protocol the server is listening on.

Mock the fetch handler for a running server.

This feature is not fully implemented yet. It doesn't normalize URLs consistently in all cases and it doesn't yet call the error handler consistently. This needs to be fixed

Send a message to all connected ServerWebSocket subscribed to a topic

The topic to publish to

The data to send

Should the data be compressed? Ignored if the client does not support compression.

0 if the message was dropped, -1 if backpressure was applied, or the number of bytes sent.

server.publish("chat", "Hello World");

Undo a call to Server.unref

If the Server has already been stopped, this does nothing.

If Server.ref is called multiple times, this does nothing. Think of it as a boolean toggle.

Update the fetch and error handlers without restarting the server.

This is useful if you want to change the behavior of your server without restarting it or for hot reloading.

// create the server
const server = Bun.serve({
fetch(request) {
return new Response("Hello World v1")
}
});

// Update the server to return a different response
server.reload({
fetch(request) {
return new Response("Hello World v2")
}
});

Passing other options such as port or hostname won't do anything.

Returns the client IP address and port of the given Request. If the request was closed or is a unix socket, returns null.

export default {
async fetch(request, server) {
return new Response(server.requestIP(request));
}
}

Stop listening to prevent new connections from being accepted.

By default, it does not cancel in-flight requests or websockets. That means it may take some time before all network activity stops.

Immediately terminate in-flight requests, websockets, and stop accepting new connections.

A count of connections subscribed to a given topic

This operation will loop through each topic internally to get the count.

the websocket topic to check how many subscribers are connected to

the number of subscribers

Reset the idleTimeout of the given Request to the number in seconds. 0 means no timeout.

export default {
async fetch(request, server) {
server.timeout(request, 60);
await Bun.sleep(30000);
return new Response("30 seconds have passed");
}
}

Don't keep the process alive if this server is the only thing left. Active connections may continue to keep the process alive.

By default, the server is ref'd.

To prevent new connections from being accepted, use Server.stop

Upgrade a Request to a ServerWebSocket

The Request to upgrade

Pass headers or attach data to the ServerWebSocket

true if the upgrade was successful and false if it failed

import { serve } from "bun";
const server: Bun.Server: string }> = serve({
websocket: {
open: (ws) => {
console.log("Client connected");
},
message: (ws, message) => {
console.log("Client sent message", message);
},
close: (ws) => {
console.log("Client disconnected");
},
},
fetch(req, server) {
const url = new URL(req.url);
if (url.pathname === "/chat") {
const upgraded = server.upgrade(req, {
data: {user: "John Doe"}
});
if (!upgraded) {
return new Response("Upgrade failed", { status: 400 });
}
}
return new Response("Hello World");
},
});

What you pass to data is available on the ServerWebSocket.data property