Custom Integrations#

app.integrate() mounts a raw Bun handler at one exact pathname on the same server as Buntok. It is not Socket.IO-specific - it works for any library or handler that exposes Bun's (request, server) => Response contract, with an optional WebSocket handler.

Info
Use app.integrate() for third-party handlers that need the live Bun.Server (WebSocket upgrades, polling transports, raw proxies). For normal HTTP endpoints, prefer app.get(), app.group(), and app.static().

Contract#

OptionTypeDescription
pathstringExact pathname to intercept, e.g. /socket.io/ (required)
labelstringHuman-readable name shown in the startup banner
fetch(request, server) => Response | Promise<Response>Raw Bun request handler (required); runs before router/middleware
websocketRecord<string, unknown>Bun WebSocket handler for connections upgraded by this integration
serveRecord<string, unknown>Extra Bun.serve options merged at listen(); fetch, websocket, routes, and port are ignored

HTTP-only Handler#

The integration owns every method on its pathname. Middleware, Buntok context, and the AOT router are bypassed:

typescript
app.integrate({
  path: "/vendor/health/",
  label: "Vendor Health",
  fetch: () => new Response("ok", {
    headers: { "Content-Type": "text/plain" },
  }),
});

// GET /vendor/health/ → "ok"
// POST /vendor/health/ → also handled by the integration

HTTP + WebSocket#

When the integration upgrades a connection via server.upgrade(), its websocket handler receives the connection. Buntok's app.ws() routes keep working at the same time - connections are separated by the handler marker Buntok attaches during upgrade:

typescript
app.integrate({
  path: "/custom-ws/",
  label: "Custom WS",
  fetch: (request, server) => {
    const upgraded = server.upgrade(request, {
      data: { source: "custom" },
    });
    return upgraded
      ? undefined as unknown as Response
      : new Response("Upgrade Required", { status: 426 });
  },
  websocket: {
    open(ws) {
      ws.send("custom connected");
    },
    message(ws, message) {
      ws.send(message);
    },
  },
  serve: { idleTimeout: 30 },
});

// Still works - Buntok routes its own WebSocket connections.
app.ws("/chat", {
  open(ws) {
    ws.send("buntok connected");
  },
});
Warning
Only one third-party WebSocket handler can be mounted. Bun has a single global websocket handler; Buntok composes that one handler with app.ws() and throws at startup if more than one integration provides websocket.

Socket.IO#

For Socket.IO, use the official socketIOPlugin instead of wiring the engine manually. The plugin calls app.integrate() for both the polling transport and the WebSocket handler.

typescript
import { Buntok } from "@buntok/core";
import { socketIOPlugin } from "@buntok/core/plugins/socket-io";
import { Server } from "socket.io";

const app = new Buntok();
const io = new Server();

await app.plugin(socketIOPlugin({ io }));
app.listen(1212);

The startup banner prints the mount path:

bash
Buntok v3.0.0 ready in 5ms

Environment:  development
Listening on: http://localhost:1212
Socket.IO:    http://localhost:1212/socket.io/

Common Use Cases#

  • Socket.IO / Engine.IO via @socket.io/bun-engine
  • GraphQL subscriptions or other WebSocket protocols with a Bun adapter
  • Raw webhook receivers that need the original request/response cycle
  • Streaming proxies and third-party handlers that expose (request, server) => Response
  • Vendor health checks or internal diagnostics mounted at a dedicated path

Limitations#

  • Exact pathname only - no prefix, params, wildcard, or catch-all. Mount multiple integrations for multiple paths.
  • Bypasses Buntok - no middleware, auth, ctx, DI, request logging, error handler, or lifecycle hooks. The integration must handle its own errors.
  • Needs a live server - integrations are skipped in serverless dispatch such as app.fetch(request) without a server argument.
  • Serve options are merged at listen time - adding an integration after listen() refreshes its WebSocket handler and routes, but not immutable serve options.
Info
When in doubt, implement the endpoint as a normal Buntok route. Reach for app.integrate() only when a third-party handler needs raw access to the Bun server or owns its own protocol lifecycle.