DocsReferenceGuidesBlog
Discord logo
Discord
GitHub logo

Serve

TServe
Bun

Symbol

Serve

type Serve<WebSocketDataType = undefined> = ServeOptions | TLSServeOptions | UnixServeOptions | UnixTLSServeOptions | WebSocketServeOptions<WebSocketDataType> | TLSWebSocketServeOptions<WebSocketDataType> | UnixWebSocketServeOptions<WebSocketDataType> | UnixTLSWebSocketServeOptions<WebSocketDataType>

The type of options that can be passed to serve

Referenced types

interface ServeOptions

  • development?: boolean | { hmr: boolean }

    Render contextual errors? This enables bun's error page

  • error?: (this: Server, error: ErrorLike) => void | Promise<void> | Response | Promise<Response>
  • hostname?: string

    What hostname should the server listen on?

    "127.0.0.1" // Only listen locally
  • id?: null | string

    Uniquely identify a server instance with an ID

    When bun is started with the --hot flag

    This string will be used to hot reload the server without interrupting pending requests or websockets. If not provided, a value will be generated. To disable hot reloading, set this value to null.

    When bun is not started with the --hot flag

    This string will currently do nothing. But in the future it could be useful for logs or metrics.

  • idleTimeout?: number

    Sets the the number of seconds to wait before timing out a connection due to inactivity.

    Default is 10 seconds.

  • ipv6Only?: boolean

    Whether the IPV6_V6ONLY flag should be set.

  • maxRequestBodySize?: number

    What is the maximum size of a request body? (in bytes)

  • port?: string | number

    What port should the server listen on?

  • reusePort?: boolean

    Whether the SO_REUSEPORT flag should be set.

    This allows multiple processes to bind to the same port, which is useful for load balancing.

  • unix?: undefined

    If set, the HTTP server will listen on a unix socket instead of a port. (Cannot be used with hostname+port)

  • fetch(this: Server, request: Request, server: Server): Response | Promise<Response>

    Handle HTTP requests

    Respond to Request objects with a Response object.

interface UnixServeOptions

  • development?: boolean | { hmr: boolean }

    Render contextual errors? This enables bun's error page

  • error?: (this: Server, error: ErrorLike) => void | Promise<void> | Response | Promise<Response>
  • id?: null | string

    Uniquely identify a server instance with an ID

    When bun is started with the --hot flag

    This string will be used to hot reload the server without interrupting pending requests or websockets. If not provided, a value will be generated. To disable hot reloading, set this value to null.

    When bun is not started with the --hot flag

    This string will currently do nothing. But in the future it could be useful for logs or metrics.

  • maxRequestBodySize?: number

    What is the maximum size of a request body? (in bytes)

  • unix: string

    If set, the HTTP server will listen on a unix socket instead of a port. (Cannot be used with hostname+port)

  • fetch(this: Server, request: Request, server: Server): Response | Promise<Response>

    Handle HTTP requests

    Respond to Request objects with a Response object.

interface WebSocketServeOptions<WebSocketDataType = undefined>

  • development?: boolean | { hmr: boolean }

    Render contextual errors? This enables bun's error page

  • error?: (this: Server, error: ErrorLike) => void | Promise<void> | Response | Promise<Response>
  • hostname?: string

    What hostname should the server listen on?

    "127.0.0.1" // Only listen locally
  • id?: null | string

    Uniquely identify a server instance with an ID

    When bun is started with the --hot flag

    This string will be used to hot reload the server without interrupting pending requests or websockets. If not provided, a value will be generated. To disable hot reloading, set this value to null.

    When bun is not started with the --hot flag

    This string will currently do nothing. But in the future it could be useful for logs or metrics.

  • maxRequestBodySize?: number

    What is the maximum size of a request body? (in bytes)

  • port?: string | number

    What port should the server listen on?

  • websocket: WebSocketHandler<WebSocketDataType>

    Enable websockets with Bun.serve

    For simpler type safety, see Bun.websocket

    Bun.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);
     if (!upgraded) {
       return new Response("Upgrade failed", { status: 400 });
     }
   }
   return new Response("Hello World");
 },
});

    Upgrade a Request to a ServerWebSocket via Server.upgrade

    Pass data in @{link Server.upgrade} to attach data to the ServerWebSocket.data property

  • fetch(this: Server, request: Request, server: Server): undefined | void | Response | Promise<undefined | void | Response>

    Handle HTTP requests or upgrade them to a ServerWebSocket

    Respond to Request objects with a Response object.

interface UnixWebSocketServeOptions<WebSocketDataType = undefined>

  • development?: boolean | { hmr: boolean }

    Render contextual errors? This enables bun's error page

  • error?: (this: Server, error: ErrorLike) => void | Promise<void> | Response | Promise<Response>
  • id?: null | string

    Uniquely identify a server instance with an ID

    When bun is started with the --hot flag

    This string will be used to hot reload the server without interrupting pending requests or websockets. If not provided, a value will be generated. To disable hot reloading, set this value to null.

    When bun is not started with the --hot flag

    This string will currently do nothing. But in the future it could be useful for logs or metrics.

  • maxRequestBodySize?: number

    What is the maximum size of a request body? (in bytes)

  • unix: string

    If set, the HTTP server will listen on a unix socket instead of a port. (Cannot be used with hostname+port)

  • websocket: WebSocketHandler<WebSocketDataType>

    Enable websockets with Bun.serve

    For simpler type safety, see Bun.websocket

    import { serve } from "bun";
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);
     if (!upgraded) {
       return new Response("Upgrade failed", { status: 400 });
     }
   }
   return new Response("Hello World");
 },
});

    Upgrade a Request to a ServerWebSocket via Server.upgrade

    Pass data in @{link Server.upgrade} to attach data to the ServerWebSocket.data property

  • fetch(this: Server, request: Request, server: Server): undefined | Response | Promise<undefined | Response>

    Handle HTTP requests or upgrade them to a ServerWebSocket

    Respond to Request objects with a Response object.