Build once, run Web Requests.

Local production

bun run build
bun run start

turtle start imports dist/runtime/handle-request.js, serves public files, delegates requests to the compiled handler, and schedules best-effort after() tasks.

Vercel entry

// api/index.ts
import { createVercelHandler } from "turtle/vercel";

type Runtime = { handleRequest(request: Request): Promise<Response> };
const runtime = import(new URL("../dist/runtime/handle-request.js", import.meta.url).href) as Promise<Runtime>;

async function handleRequest(request: Request) {
  return (await runtime).handleRequest(request);
}

export default createVercelHandler(handleRequest);

// vercel.json
{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "bunVersion": "1.x",
  "buildCommand": "bun run build",
  "rewrites": [{ "source": "/(.*)", "destination": "/api" }],
  "functions": {
    "api/index.ts": { "includeFiles": "{dist/**,public/**}" }
  }
}

Keep api/, public/, configuration, and Vercel settings inside the application package. The monorepo root should coordinate workspaces, not impersonate one application.

Runtime and security headers

Turtle responses identify Bun, disable MIME sniffing, use strict-origin referrer policy, and set a restrictive content security policy: self-hosted styles/images/connections, no objects, no base URI, and no framing. Inline script remains allowed for streamed Flight bootstrap chunks; applications should account for that constraint in security review.

Diagnostics

Diagnostics are private by default. With diagnostics: true, /__runtime reports Bun/framework/build and route counts, while /__assets returns the non-sensitive asset manifest. Do not enable them accidentally.

Operational checklist

• Build and typecheck from a clean dependency install.
• Scan browser and SSR outputs for secret sentinels and server-only inputs.
• Exercise HTML first-byte streaming and Flight content types through the real host.
• Verify redirects, error/not-found UI, route handlers, public files, and background adapter behavior.
• Keep critical mutations awaited and idempotent; treat deferred work as at-most-once.
• Deploy close to stateful infrastructure to minimize physical latency.