The Bun adapter provides utilities for running Hono applications on Bun, including static file serving, SSG support, WebSocket handling, and server utilities.
Import
import {
serveStatic,
toSSG,
bunFileSystemModule,
upgradeWebSocket,
websocket,
createBunWebSocket,
getConnInfo,
getBunServer
} from 'hono/bun'
import type { BunWebSocketData, BunWebSocketHandler } from 'hono/bun'
Functions
serveStatic()
Middleware for serving static files from the local file system in Bun.
function serveStatic<E extends Env = Env>(
options: ServeStaticOptions<E>
): MiddlewareHandler
Parameters
options.root - string (optional) - Root directory path (default: '.')options.path - string (optional) - Base path for static filesoptions.rewriteRequestPath - (path: string) => string (optional) - Function to rewrite request paths- Additional options from base
ServeStaticOptions
Example
import { Hono } from 'hono'
import { serveStatic } from 'hono/bun'
const app = new Hono()
app.use('/static/*', serveStatic({ root: './public' }))
app.use('/favicon.ico', serveStatic({ path: './public/favicon.ico' }))
export default app
upgradeWebSocket()
Helper function to upgrade HTTP connections to WebSocket connections in Bun.
function upgradeWebSocket<T>(
createEvents: (c: Context) => WSEvents
): MiddlewareHandler
Parameters
createEvents - Function that receives context and returns WebSocket event handlers
Example
import { Hono } from 'hono'
import { upgradeWebSocket } from 'hono/bun'
const app = new Hono()
app.get(
'/ws',
upgradeWebSocket((c) => {
return {
onOpen: (evt, ws) => {
console.log('Connection opened')
},
onMessage: (event, ws) => {
console.log(`Message: ${event.data}`)
ws.send('Hello from Bun!')
},
onClose: (evt, ws) => {
console.log('Connection closed')
},
}
})
)
export default {
port: 3000,
fetch: app.fetch,
websocket, // Required for WebSocket support
}
websocket
Bun WebSocket handler that must be exported alongside your app for WebSocket functionality.
const websocket: BunWebSocketHandler<BunWebSocketData>
Example
import { Hono } from 'hono'
import { upgradeWebSocket, websocket } from 'hono/bun'
const app = new Hono()
app.get('/ws', upgradeWebSocket((c) => ({ /* ... */ })))
export default {
port: 3000,
fetch: app.fetch,
websocket, // Export the websocket handler
}
createBunWebSocket()
createBunWebSocket is deprecated. Import upgradeWebSocket and websocket directly from hono/bun instead.
function createBunWebSocket<T>(): {
upgradeWebSocket: UpgradeWebSocket<T>
websocket: BunWebSocketHandler<BunWebSocketData>
}
toSSG()
toSSG is an experimental feature. The API might be changed.
function toSSG(
app: Hono,
options?: ToSSGOptions
): Promise<ToSSGResult>
Example
import { Hono } from 'hono'
import { toSSG } from 'hono/bun'
const app = new Hono()
app.get('/', (c) => c.html('<h1>Home</h1>'))
app.get('/about', (c) => c.html('<h1>About</h1>'))
await toSSG(app, { dir: './dist' })
bunFileSystemModule
bunFileSystemModule is an experimental feature. The API might be changed.
toSSG.
const bunFileSystemModule: FileSystemModule
getConnInfo()
Extracts connection information from the Bun request.
function getConnInfo(c: Context): ConnInfo
Returns
interface ConnInfo {
remote: {
address?: string // Client IP address
addressType?: string // 'IPv4' or 'IPv6'
port?: number // Client port
}
}
Example
import { Hono } from 'hono'
import { getConnInfo } from 'hono/bun'
const app = new Hono()
app.get('/', (c) => {
const info = getConnInfo(c)
return c.json({
ip: info.remote.address,
type: info.remote.addressType,
port: info.remote.port
})
})
export default {
port: 3000,
fetch: app.fetch,
}
getBunServer()
Gets the Bun server instance from the context.
function getBunServer<T>(c: Context): T | undefined
Returns
The Bun server object, or undefined if not available.
Example
import { Hono } from 'hono'
import { getBunServer } from 'hono/bun'
const app = new Hono()
app.get('/server-info', (c) => {
const server = getBunServer(c)
if (!server) {
return c.text('Server info not available', 500)
}
return c.json({
port: server.port,
hostname: server.hostname
})
})
export default app
Types
BunWebSocketData
Internal data structure for WebSocket connections.
interface BunWebSocketData {
events: WSEvents
url: URL
protocol: string
}
BunWebSocketHandler
Bun-specific WebSocket handler interface.
interface BunWebSocketHandler<T> {
open(ws: BunServerWebSocket<T>): void
close(ws: BunServerWebSocket<T>, code?: number, reason?: string): void
message(ws: BunServerWebSocket<T>, message: string | { buffer: ArrayBufferLike }): void
}
- Bun uses
Bun.file() for optimized file serving
- Connection info is retrieved via
server.requestIP()
- WebSocket support requires exporting the
websocket handler alongside fetch
- The server instance must be passed in the second argument of
app.fetch() for getConnInfo and WebSocket to work
- Bun provides excellent performance for static file serving
Running Your Application
Basic Server
// server.ts
import { Hono } from 'hono'
const app = new Hono()
app.get('/', (c) => c.text('Hello Bun!'))
export default {
port: 3000,
fetch: app.fetch,
}
With WebSocket
import { Hono } from 'hono'
import { upgradeWebSocket, websocket } from 'hono/bun'
const app = new Hono()
app.get('/ws', upgradeWebSocket((c) => ({
onMessage: (evt, ws) => ws.send(`Echo: ${evt.data}`),
})))
export default {
port: 3000,
fetch: app.fetch,
websocket, // Required for WebSocket
}
See Also
