Cloudflare Pages

API reference for the Cloudflare Pages adapter

The Cloudflare Pages adapter provides utilities for running Hono applications on Cloudflare Pages Functions.

Import

import { handle, handleMiddleware, serveStatic, getConnInfo } from 'hono/cloudflare-pages'
import type { EventContext } from 'hono/cloudflare-pages'

Functions

handle()

Converts a Hono application to a Cloudflare Pages Function handler.

function handle<E extends Env, S extends Schema, BasePath extends string>(
  app: Hono<E, S, BasePath>
): PagesFunction<E['Bindings']>

Parameters

• app - The Hono application instance

Returns

A Pages Function that can be exported as onRequest or other Pages Function exports.

Example

// functions/_middleware.ts
import { Hono } from 'hono'
import { handle } from 'hono/cloudflare-pages'

const app = new Hono()

app.get('/api/*', (c) => c.text('Hello from Cloudflare Pages!'))
app.post('/api/form', async (c) => {
  const body = await c.req.parseBody()
  return c.json({ success: true, data: body })
})

export const onRequest = handle(app)

handleMiddleware()

Wraps a Hono middleware to work as a Cloudflare Pages Function middleware.

function handleMiddleware<E extends Env, P extends string, I extends Input>(
  middleware: MiddlewareHandler<E, P, I>
): PagesFunction<E['Bindings']>

Parameters

• middleware - Hono middleware handler

Returns

A Pages Function that executes the middleware and passes through to the next function.

Example

// functions/_middleware.ts
import { handleMiddleware } from 'hono/cloudflare-pages'
import { logger } from 'hono/logger'

export const onRequest = handleMiddleware(logger())

serveStatic()

Middleware for serving static files from Cloudflare Pages’ ASSETS binding.

function serveStatic(): MiddlewareHandler

This is for advanced mode. See Cloudflare Pages Functions Advanced Mode.

Example

import { Hono } from 'hono'
import { serveStatic } from 'hono/cloudflare-pages'

const app = new Hono()

// Serve static files from the public directory
app.use('/static/*', serveStatic())

app.get('/api/hello', (c) => c.text('Hello API'))

export const onRequest = handle(app)

getConnInfo()

Extracts connection information from the Cloudflare Pages 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 { handle, getConnInfo } from 'hono/cloudflare-pages'

const app = new Hono()

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

export const onRequest = handle(app)

Types

EventContext

The Cloudflare Pages event context passed to Functions.

interface EventContext<Env = {}, P extends string = any, Data = Record<string, unknown>> {
  request: Request
  functionPath: string
  waitUntil: (promise: Promise<unknown>) => void
  passThroughOnException: () => void
  next: (input?: Request | string, init?: RequestInit) => Promise<Response>
  env: Env & { ASSETS: { fetch: typeof fetch } }
  params: Params<P>
  data: Data
}

Accessing EventContext

The event context is available in c.env.eventContext:

import { Hono } from 'hono'
import { handle } from 'hono/cloudflare-pages'
import type { EventContext } from 'hono/cloudflare-pages'

type Env = {
  Bindings: {
    MY_KV: KVNamespace
    eventContext: EventContext
  }
}

const app = new Hono<Env>()

app.get('/api/data', async (c) => {
  const { eventContext } = c.env
  
  // Use waitUntil for background tasks
  eventContext.waitUntil(
    c.env.MY_KV.put('last-access', new Date().toISOString())
  )
  
  return c.json({ functionPath: eventContext.functionPath })
})

export const onRequest = handle(app)

Platform-Specific Notes

• Cloudflare Pages Functions run on the Cloudflare Workers runtime
• Use the ASSETS binding to serve static files
• The eventContext provides access to Pages-specific functionality like waitUntil and passThroughOnException
• Client IP is extracted from the cf-connecting-ip header
• Pages Functions support file-based routing in the functions/ directory

Deployment

Cloudflare Pages expects Functions in the functions/ directory:

project/
├── functions/
│   ├── _middleware.ts    # Global middleware
│   ├── api/
│   │   └── [[path]].ts   # Catch-all for /api/*
│   └── index.ts
└── public/
    └── index.html

See Also

• Cloudflare Pages Documentation
• Pages Functions
• Advanced Mode