Bun

API reference for the Bun adapter

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 files
• options.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.

Legacy function to create a Bun WebSocket handler.

function createBunWebSocket<T>(): {
  upgradeWebSocket: UpgradeWebSocket<T>
  websocket: BunWebSocketHandler<BunWebSocketData>
}

toSSG()

toSSG is an experimental feature. The API might be changed.

Generates static HTML files from your Hono application (Static Site Generation).

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.

File system module implementation for Bun, used by 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
}

Platform-Specific Notes

• 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,
}

bun run server.ts

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

• Bun Documentation
• Bun WebSocket API
• Bun.serve