Cloudflare Workers

API reference for the Cloudflare Workers adapter

The Cloudflare Workers adapter provides utilities for running Hono applications on Cloudflare Workers.

Import

import { serveStatic, upgradeWebSocket, getConnInfo } from 'hono/cloudflare-workers'

Functions

serveStatic()

serveStatic in the Cloudflare Workers adapter is deprecated. You can serve static files directly using Cloudflare Static Assets.

Cloudflare Static Assets is currently in open beta. If this doesn’t work for you, please consider using Cloudflare Pages. You can start to create the Cloudflare Pages application with the npm create hono@latest command.

Middleware for serving static files from Cloudflare Workers KV.

function serveStatic<E extends Env = Env>(
  options: ServeStaticOptions<E>
): MiddlewareHandler

Parameters

• options.manifest - object | string - Asset manifest for KV
• options.namespace - KVNamespace (optional) - KV namespace to use
• Additional options from base ServeStaticOptions

Example

import { Hono } from 'hono'
import { serveStatic } from 'hono/cloudflare-workers'
import manifest from '__STATIC_CONTENT_MANIFEST'

const app = new Hono()

app.get('/static/*', serveStatic({ 
  manifest,
  namespace: env.__STATIC_CONTENT 
}))

export default app

upgradeWebSocket()

Helper function to upgrade HTTP connections to WebSocket connections in Cloudflare Workers.

function upgradeWebSocket<T>(
  createEvents: (c: Context) => WSEvents
): MiddlewareHandler

Parameters

• createEvents - Function that receives context and returns WebSocket event handlers:
  • onMessage - Called when a message is received
  • onClose - Called when the connection closes
  • onError - Called on error

Cloudflare Workers doesn’t support the onOpen event. The connection is established after the handler returns.

Example

import { Hono } from 'hono'
import { upgradeWebSocket } from 'hono/cloudflare-workers'

const app = new Hono()

app.get(
  '/ws',
  upgradeWebSocket((c) => {
    return {
      onMessage(event, ws) {
        console.log(`Message from client: ${event.data}`)
        ws.send('Hello from server!')
      },
      onClose: () => {
        console.log('Connection closed')
      },
      onError(evt) {
        console.log('WebSocket error:', evt)
      },
    }
  })
)

export default app

getConnInfo()

Extracts connection information from the Cloudflare Workers request.

function getConnInfo(c: Context): ConnInfo

Returns

interface ConnInfo {
  remote: {
    address?: string // Client IP from cf-connecting-ip header
  }
}

Example

import { Hono } from 'hono'
import { getConnInfo } from 'hono/cloudflare-workers'

const app = new Hono()

app.get('/', (c) => {
  const info = getConnInfo(c)
  return c.text(`Your IP: ${info.remote.address}`)
})

export default app

Platform-Specific Notes

• Cloudflare Workers uses the cf-connecting-ip header to identify the client’s IP address
• WebSocket connections require special handling with WebSocketPair
• The onOpen event is not available for WebSockets in Cloudflare Workers
• Static file serving is deprecated in favor of Cloudflare Static Assets or Cloudflare Pages

See Also

• Cloudflare Workers Documentation
• Cloudflare Static Assets
• WebSocket API in Workers