MiniFW | mini API Reference

`interface MiniOptions`

interface MiniOptions extends Omit<Bun.Serve.Options<undefined>, "routes"> {
  config?: MiniConfig;
  development?: Development;
  error?: object;
  fetch?: object | object | object | object;
  hostname?: "0.0.0.0" | "127.0.0.1" | "localhost" | string & object;
  http1?: boolean;
  http3?: boolean;
  id?: string | null;
  idleTimeout?: number;
  ipv6Only?: boolean;
  layouts?: Record<string, MiniLayout>;
  maxRequestBodySize?: number;
  partials?: Record<string, MiniPartial>;
  port?: string | number;
  reusePort?: boolean;
  routes?: Record<string, MiniPage | BaseRouteValue | Handler<BunRequest<string>, Server<undefined>, Response> | Partial<Record<HTTPMethod, Response | Handler<BunRequest<string>, Server<undefined>, Response>>> | Handler<BunRequest<string>, Server<undefined>, void | Response | undefined> | Partial<Record<HTTPMethod, Response | Handler<BunRequest<string>, Server<undefined>, void | Response | undefined>>>>;
  tls?: TLSOptions | TLSOptions[];
  unix?: string;
  websocket?: WebSocketHandler<undefined>;
}

Configuration options for mini. Extends Bun's serve options with MiniFW-specific routing and layout fields.

routes is omitted from the base Bun options and accepts either a MiniPage or a native Bun route entry for each path pattern.

`property config`

Document and browser behavior managed by MiniFW.

MiniConfig

`property development`

Render contextual errors? This enables bun's error page

Development

`property error`

Callback called when an error is thrown during request handling

object

error: (error) => {
  return new Response("Internal Server Error", { status: 500 });
}

`property fetch`

object | object | object | object

`property hostname`

What hostname should the server listen on?

"0.0.0.0" | "127.0.0.1" | "localhost" | string & object

"127.0.0.1" // Only listen locally

"remix.run" // Only listen on remix.run

note: hostname should not include a {@link port}

`property http1`

Listen for HTTP/1.1 over TCP. Set to false together with http3: true to serve HTTP/3 only.

boolean

`property http3`

Also listen for HTTP/3 (QUIC) on the same port. Requires tls.

boolean

`property id`

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.

string | null

`property idleTimeout`

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

number

`property ipv6Only`

Whether the IPV6_V6ONLY flag should be set.

boolean

`property layouts`

Route patterns mapped to composable layout shells.

Record<string, MiniLayout>

`property maxRequestBodySize`

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

number

`property partials`

Map of partial names to MiniPartial instances. Each partial is served at /partial/<name>.

Record<string, MiniPartial>

`property port`

What port should the server listen on?

string | number

`property reusePort`

Whether the SO_REUSEPORT flag should be set.

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

boolean

`property routes`

Map of URL path patterns to MiniPage instances or native Bun route entries. Native entries are passed directly to Bun.serve.

Record<string, MiniPage | BaseRouteValue | Handler<BunRequest<string>, Server<undefined>, Response> | Partial<Record<HTTPMethod, Response | Handler<BunRequest<string>, Server<undefined>, Response>>> | Handler<BunRequest<string>, Server<undefined>, void | Response | undefined> | Partial<Record<HTTPMethod, Response | Handler<BunRequest<string>, Server<undefined>, void | Response | undefined>>>>

`property tls`

Set options for using TLS with this server

TLSOptions | TLSOptions[]

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")],
  },
});

`property unix`

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

string

`property websocket`

Enable websockets with Bun.serve

Upgrade a Request to a ServerWebSocket via Server.upgrade

Pass data in Server.upgrade to attach data to the ServerWebSocket.data property

WebSocketHandler<undefined>

const server: Bun.Server = 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");
 },
});

`function mini`

mini(options: MiniOptions): Server<undefined>

Start a MiniFW server.

options: Server configuration including routes, partials, layouts, and document config.

Returns:

A running Bun.Server instance.

Sections

@calvinbonner/minifw API Reference

`core/mini`