BuildDocsReferenceGuidesBlog
Discord logo
Discord
GitHub logo
NServe
Bun

namespace

Serve

namespace Serve

  • interface BaseServeOptions<WebSocketData>

    • development?: Development

      Render contextual errors? This enables bun's error page

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

      Callback called when an error is thrown during request handling

      error: (error) => {
  return new Response("Internal Server Error", { status: 500 });
}
    • 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)

    • tls?: TLSOptions | TLSOptions[]

      Set options for using TLS with this server

      const server = Bun.serve({
  fetch: request => new Response("Welcome to Bun!"),
  tls: {
    cert: Bun.file("cert.pem"),
    key: Bun.file("key.pem"),
    ca: [Bun.file("ca1.pem"), Bun.file("ca2.pem")],
  },
});

  • interface HostnamePortServeOptions<WebSocketData>

    • development?: Development

      Render contextual errors? This enables bun's error page

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

      Callback called when an error is thrown during request handling

      error: (error) => {
  return new Response("Internal Server Error", { status: 500 });
}
    • hostname?: string & {} | '0.0.0.0' | '127.0.0.1' | 'localhost'

      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.

    • 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.

    • tls?: TLSOptions | TLSOptions[]

      Set options for using TLS with this server

      const server = Bun.serve({
  fetch: request => new Response("Welcome to Bun!"),
  tls: {
    cert: Bun.file("cert.pem"),
    key: Bun.file("key.pem"),
    ca: [Bun.file("ca1.pem"), Bun.file("ca2.pem")],
  },
});

  • interface UnixServeOptions<WebSocketData>

    • development?: Development

      Render contextual errors? This enables bun's error page

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

      Callback called when an error is thrown during request handling

      error: (error) => {
  return new Response("Internal Server Error", { status: 500 });
}
    • 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)

    • tls?: TLSOptions | TLSOptions[]

      Set options for using TLS with this server

      const server = Bun.serve({
  fetch: request => new Response("Welcome to Bun!"),
  tls: {
    cert: Bun.file("cert.pem"),
    key: Bun.file("key.pem"),
    ca: [Bun.file("ca1.pem"), Bun.file("ca2.pem")],
  },
});
    • unix?: string

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

  • type Development = boolean | { chromeDevToolsAutomaticWorkspaceFolders: boolean; console: boolean; hmr: boolean }

    Development configuration for Bun.serve

  • type ExtractRouteParams<T> = T extends `${string}:${infer Param}/${infer Rest}` ? { [K in Param]: string } & ExtractRouteParams<Rest> : T extends `${string}:${infer Param}` ? { [K in Param]: string } : T extends `${string}*` ? {} : {}
  • type FetchOrRoutes<WebSocketData, R extends string> = { routes: Routes<WebSocketData, R>; fetch(this: Server<WebSocketData>, req: Request, server: Server<WebSocketData>): MaybePromise<Response> } | { routes: Routes<WebSocketData, R>; fetch(this: Server<WebSocketData>, req: Request, server: Server<WebSocketData>): MaybePromise<Response> }
  • type FetchOrRoutesWithWebSocket<WebSocketData, R extends string> = { websocket: WebSocketHandler<WebSocketData> } & { routes: RoutesWithUpgrade<WebSocketData, R>; fetch(this: Server<WebSocketData>, req: Request, server: Server<WebSocketData>): MaybePromise<undefined | void | Response> } | { routes: RoutesWithUpgrade<WebSocketData, R>; fetch(this: Server<WebSocketData>, req: Request, server: Server<WebSocketData>): MaybePromise<undefined | void | Response> }
  • type Handler<Req extends Request, S, Res> = (request: Req, server: S) => MaybePromise<Res>
  • type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'
  • type Options<WebSocketData, R extends string = never> = Bun.__internal.XOR<HostnamePortServeOptions<WebSocketData>, UnixServeOptions<WebSocketData>> & Bun.__internal.XOR<FetchOrRoutes<WebSocketData, R>, FetchOrRoutesWithWebSocket<WebSocketData, R>>

    The type of options that can be passed to serve, with support for routes and a safer requirement for fetch

    export default {
  fetch: req => Response.json(req.url),

  websocket: {
    message(ws) {
      ws.data.name; // string
    },
  },
} satisfies Bun.Serve.Options<{ name: string }>;
  • type Routes<WebSocketData, R extends string> = { [K in R]: BaseRouteValue | Handler<BunRequest<Path>, Server<WebSocketData>, Response> | Partial<Record<HTTPMethod, Handler<BunRequest<Path>, Server<WebSocketData>, Response>>> }
  • type RoutesWithUpgrade<WebSocketData, R extends string> = { [K in R]: BaseRouteValue | Handler<BunRequest<Path>, Server<WebSocketData>, Response | undefined | void> | Partial<Record<HTTPMethod, Handler<BunRequest<Path>, Server<WebSocketData>, Response | undefined | void>>> }