type

Serve.BaseRouteValue

Referenced types

class Response

This Fetch API interface represents the response to a request.

MDN Reference

interface HTMLBundle

The result of importing an HTML file, at runtime or at build time.

import app from "./index.html";
  • files?: { headers: { content-type: string; etag: string }; input: string; isEntry: boolean; loader: Loader; path: string }[]

    Array of generated output files with metadata. This only exists when built ahead of time with Bun.build or bun build

  • index: string

interface BunFile

Blob powered by the fastest system calls available for operating on files.

This Blob is lazy: it does no work until you read from it.

  • size is not valid until the contents of the file are read at least once.
  • type is auto-set based on the file extension when possible
const file = Bun.file("./hello.json");
console.log(file.type); // "application/json"
console.log(await file.text()); // '{"hello":"world"}'
  • lastModified: number

    A UNIX timestamp indicating when the file was last modified.

  • readonly name?: string

    The name or path of the file, as specified in the constructor.

  • readonly size: number
  • readonly type: string

  • Returns a promise that resolves to the contents of the blob as an ArrayBuffer

  • bytes(): Promise<Uint8Array<ArrayBufferLike>>;

    Returns a promise that resolves to the contents of the blob as a Uint8Array (array of bytes). Equivalent to new Uint8Array(await blob.arrayBuffer())

  • delete(): Promise<void>;

    Deletes the file (same as unlink)

  • exists(): Promise<boolean>;

    Does the file exist?

    This returns true for regular files and FIFOs. It returns false for directories. A race condition can occur where the file is deleted or renamed after this is called but before you open it.

    This does a system call to check if the file exists, which can be slow.

    If using this in an HTTP server, it's faster to instead use return new Response(Bun.file(path)) and then an error handler to handle exceptions.

    Instead of checking for a file's existence and then performing the operation, it is faster to just perform the operation and handle the error.

    For empty Blob, this always returns true.

  • formData(): Promise<FormData>;

    Read the data from the blob as a FormData object.

    This first decodes the data from UTF-8, then parses it as a multipart/form-data body or an application/x-www-form-urlencoded body.

    The blob's type property determines the format of the body.

    This is a non-standard addition to the Blob API, to make it conform more closely to the BodyMixin API.

  • options?: ConstructorOptions
    ): Image;

    Wrap this blob in a Bun.Image pipeline. Equivalent to new Bun.Image(this, options) — the constructor is synchronous (the underlying read happens lazily when an Image terminal is awaited), so this works on Bun.file(), Bun.s3(), fd-backed and in-memory blobs alike:

    await Bun.file("photo.jpg").image().resize(400).webp().write("thumb.webp");
  • json(): Promise<any>;

    Read the data from the blob as a JSON object.

    This first decodes the data from UTF-8, then parses it as JSON.

  • begin?: number,
    end?: number,
    contentType?: string

    Offset any operation on the file starting at begin and ending at end. end is relative to 0

    Similar to TypedArray.subarray. Does not copy the file, open the file, or modify the file.

    If begin > 0, () is slower on macOS

    @param begin

    start offset in bytes

    @param end

    absolute offset in bytes (relative to 0)

    @param contentType

    MIME type for the new BunFile

    begin?: number,
    contentType?: string

    Offset any operation on the file starting at begin

    Similar to TypedArray.subarray. Does not copy the file, open the file, or modify the file.

    If begin > 0, Bun.write() is slower on macOS

    @param begin

    start offset in bytes

    @param contentType

    MIME type for the new BunFile

    contentType?: string

    Slice the file from the beginning to the end, optionally with a new MIME type.

    @param contentType

    MIME type for the new BunFile

  • stat(): Promise<Stats>;

    Provides useful information about the file.

  • Returns a readable stream of the blob's contents

  • text(): Promise<string>;

    Returns a promise that resolves to the contents of the blob as a string

  • data: string | ArrayBuffer | SharedArrayBuffer | BunFile | Request | Response | ArrayBufferView<ArrayBufferLike>,
    options?: { highWaterMark: number }
    ): Promise<number>;

    Write data to the file. This is equivalent to using Bun.write with a BunFile.

    @param data

    The data to write.

    @param options

    The options to use for the write.

  • options?: { highWaterMark: number }

    Incremental writer for files and pipes.

interface DirectoryRouteOptions

Serve a directory tree at a URL prefix.

The route path must end in /*. The part of the request URL after the prefix is percent-decoded once and opened relative to dir. Non-canonical paths (containing ., .., empty segments, %2F, or a %XX sequence encoding a character that may appear literally in a path segment) are rejected with 404 so the served path is always the path the router matched. On Linux the open uses openat2(RESOLVE_IN_ROOT), so symlinks that would escape dir are clamped by the kernel. Routing is case-sensitive but filesystems on macOS and Windows are not by default: do not place access-controlled content inside dir and rely on an overlapping route to gate it.

Responses carry Content-Type (from the file extension), Last-Modified, a weak ETag, and support single-range Range requests. A request that resolves to a directory without a trailing / is redirected (301) to the trailing-slash URL; with the trailing slash, index.html from that directory is served. Missing files return 404.

Bun.serve({
  routes: {
    "/static/*": { dir: "./public" },
  },
});
  • dir: string

    Path to the directory to serve.

  • statCache?: boolean

    Cache formatted Last-Modified strings per path so repeated requests for an unchanged file skip the date formatter. Uses ~20 KB per route.