@igloczek/astro-bun-adapter

An Astro 7 adapter for Bun's native Bun.serve() HTTP server. It supports standalone deployment and Fetch-handler middleware without a Node HTTP compatibility bridge.

Requirements

• Astro 7
• Bun 1.3.14 or newer
• Node.js 22.12 or newer for Astro's build tooling

Install

bun add @igloczek/astro-bun-adapter

Standalone server

// astro.config.ts
import { defineConfig } from "astro/config";
import bun from "@igloczek/astro-bun-adapter";

export default defineConfig({
  output: "server",
  adapter: bun({ mode: "standalone" }),
});

Build and run the generated server:

bunx astro build
bun ./dist/server/entry.mjs

Run Astro preview with Bun as the script interpreter:

bunx --bun astro preview

HOST and PORT override Astro's configured host and port at runtime.

Middleware

Middleware mode exports a web-standard (Request, context) => Promise<Response> handler. Your server is responsible for static files.

// astro.config.ts
adapter: bun({ mode: "middleware" });

// server.ts
import { handler } from "./dist/server/entry.mjs";

Bun.serve({
  port: 3000,
  fetch(request, server) {
    const clientAddress = server.requestIP(request)?.address;
    return handler(request, {
      ...(clientAddress ? { clientAddress } : {}),
      locals: { requestId: crypto.randomUUID() },
    });
  },
});

The entry module also exports normalized options and an idempotent startServer() function. Set ASTRO_BUN_AUTOSTART=disabled before importing a standalone entry when you need to call startServer() yourself.

Options

Option	Default	Purpose
mode	required	standalone or middleware
staticHeaders	false	Serve Astro-generated CSP headers for prerendered files
bodySizeLimit	Bun default	Maximum body bytes; 0/Infinity disables the limit
reusePort	false	Allow multiple Bun processes on one port
idleTimeout	Bun default (10s)	0 disables it; maximum is 255 seconds
trustedProxies	[]	Exact proxy IPs allowed to supply X-Forwarded-For
tls	none	Certificate/key paths for native TLS
experimentalDisableStreaming	false	Disable Astro HTML streaming

Trusted proxies

X-Forwarded-For is ignored unless the direct peer is listed in trustedProxies. The adapter walks the forwarding chain from right to left and returns the last untrusted address, preventing a client from forging the leftmost value through a well-behaved proxy.

X-Forwarded-Proto is applied when the first hop is http or https. That restores the public scheme behind a TLS-terminating proxy (Coolify, Caddy, Traefik) so Astro's /_image endpoint self-fetches https://your-domain/... instead of http://.... X-Forwarded-Host is never applied.

bun({
  mode: "standalone",
  trustedProxies: ["127.0.0.1", "10.0.0.10"],
});

Use the actual address returned by Bun.serve().requestIP(); IPv4-mapped IPv6 addresses and plain IPv4 addresses are distinct strings.

TLS

bun({
  mode: "standalone",
  tls: {
    certPath: "/run/secrets/tls.crt",
    keyPath: "/run/secrets/tls.key",
    caPath: "/run/secrets/ca.crt",
  },
});

Runtime environment alternatives are SERVER_CERT_PATH, SERVER_KEY_PATH, SERVER_CA_PATH, SERVER_NAME, and SERVER_KEY_PASSPHRASE. Certificate and key must always be configured together. A reverse proxy terminating TLS is usually simpler.

Static serving

Standalone mode provides:

• traversal and symlink containment inside dist/client
• dotfile denial with /.well-known support
• GET/HEAD, ETag, Last-Modified, conditional requests, and single byte ranges
• immutable caching for Astro's generated asset directory
• clean URLs, base paths, and Astro trailing-slash redirects
• Astro-generated CSP headers for prerendered routes

Unsupported multi-range requests are safely served as complete 200 responses.

Compatibility and releases

Every change is checked against the oldest supported Astro 7 release and the current Astro 7 release, using the packed npm tarball in standalone and middleware fixtures. Releases are published from GitHub Actions with npm trusted publishing and provenance.

This adapter was derived from the MIT-licensed @astrojs/node adapter and keeps its Astro integration contract intentionally close to upstream. It replaces Node's HTTP bridge with native Bun Request/Response handling.

See CHANGELOG.md, CONTRIBUTING.md, and SECURITY.md.