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.
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#
| Option | Type | Description |
|---|---|---|
| path | string | Exact pathname to intercept, e.g. /socket.io/ (required) |
| label | string | Human-readable name shown in the startup banner |
| fetch | (request, server) => Response | Promise<Response> | Raw Bun request handler (required); runs before router/middleware |
| websocket | Record<string, unknown> | Bun WebSocket handler for connections upgraded by this integration |
| serve | Record<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:
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 integrationHTTP + 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:
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");
},
});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.
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:
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 aserverargument. - Serve options are merged at listen time - adding an integration after
listen()refreshes its WebSocket handler and routes, but not immutable serve options.
app.integrate() only when a third-party handler needs raw access to the Bun server or owns its own protocol lifecycle.