bun-spa

Serve bundled SPAs (like a vite build) from a Bun server, fast and simple.

• What it does: Loads your built files from dist/ (customizable) at startup, caches them in memory, and serves them. Unknown routes fall back to index.html (also customizable).
• Why it’s fast: Everything is served directly from memory after the initial load. There are no disk reads during requests.
• Why it’s cool: You can inject dynamic content (like meta tags for social sharing) into your SPA at request time. No need for heavy frameworks like Next.js.

Install

bun add bun-spa

Quick start

import { bunSpa } from "bun-spa";

const app = await bunSpa();

Bun.serve({
  routes: {
    "/*": app
  }
});

bunSpa returns a simple request handler, so it can be passed to the fetch option as well.

Inject dynamic content (optional)

Add a placeholder to your index.html (by default bun-spa looks for <!-- bun-spa-placeholder -->) and provide an indexInjector to replace it at request time. Useful for adding dynamic meta tags for social media previews.

IMPORTANT: If you inject user-provided content, make sure to sanitize it and follow strict guidelines to prevent security issues. See escape-goat, escape-html, sanitize-html, etc.

import { htmlEscape } from "escape-goat";

const app = await bunSpa({
  indexInjector: async ({ url }) =>
    `<meta property="og:description" content="${htmlEscape(
      await fetchDescription(url)
    )}">`
});

Dynamic headers (optional)

Provide a headers callback to set per-request headers. These merge with the default Content-Type the server sets based on the file.

const app = await bunSpa({
  headers: ({ file }) => ({
    "Cache-Control": file.isIndex
      ? "no-store"
      : "public, max-age=31536000, immutable"
  })
});

API

bunSpa(options?: BunSpaOptions): Promise<(req: Request) => Promise<Response>>

BunSpaOptions:

| Option | Type | Default | Description | | -------------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | dist | string | "./dist" | Directory scanned at startup; files cached in memory. | | glob | string | "**/*" | Glob pattern for which files to load from dist/. Uses Bun.Glob syntax. | | index | string | "index.html" | SPA entry file served as fallback for unknown routes. | | indexInjectorPlaceholder | string \| RegExp | "<!-- bun-spa-placeholder -->" | Marker in index.html to be replaced at request time. | | indexInjector | (options: BunSpaCallbackOptions) => string \| Promise<string> | undefined | Returns a string that replaces the placeholder in index.html. | | headers | (options: BunSpaCallbackOptions) => Record<string, string> \| Promise<Record<string, string>> | undefined | Additional headers to send with the response. Merged with default Content-Type. | | disabled | boolean | false | If true, the returned handler always responds with disabledResponse. Files aren't loaded. | | disabledResponse | Response | new Response("bun-spa disabled", { status: 501 }) | Response returned when disabled is true. |

Other types:

interface BunSpaCallbackOptions {
  url: URL;
  req: Request;
  file: BunSpaFile;
}

interface BunSpaFile {
  type: string;
  content: ArrayBuffer;
  file: Bun.BunFile;
  isIndex: boolean;
}

Notes

• Files are read once at startup and kept in memory for fast responses.
• All unknown paths return index.html (with optional injection).
• You are responsible for ensuring the security of any dynamically injected content; this library does not perform sanitization.
• TypeScript types are included.