Hono on Cloudflare Workers

Overview

Hono was originally built for Cloudflare Workers and provides first-class support for the entire Cloudflare ecosystem including KV, D1, R2, Durable Objects, Queues, and more.

Key Features:

• Native Workers support

• Type-safe bindings access

• KV, D1, R2, Durable Objects integration

• Static asset serving

• Cloudflare Pages support

• Queue and scheduled handlers

When to Use This Skill

Use Hono on Cloudflare when:

• Building edge APIs with global distribution

• Need serverless SQLite with D1

• Building real-time apps with Durable Objects

• Storing files with R2

• Need fast key-value storage with KV

• Deploying full-stack apps to Pages

Quick Start

Create New Project

npm create hono@latest my-app

# Select: cloudflare-workers

cd my-app

npm install

npm run dev

Project Structure

my-app/

├── src/

│   └── index.ts         # Main entry point

├── wrangler.toml        # Cloudflare configuration

├── package.json

└── tsconfig.json

Basic Application

// src/index.ts

import { Hono } from 'hono'

const app = new Hono()

app.get('/', (c) => c.text('Hello Cloudflare Workers!'))

export default app

Deploy

# Deploy to Cloudflare

npx wrangler deploy

# Local development

npx wrangler dev

Environment Bindings

Typed Bindings

import { Hono } from 'hono'

// Define your bindings

type Bindings = {

  // Environment variables

  API_KEY: string

  DATABASE_URL: string

  // KV Namespaces

  MY_KV: KVNamespace

  // D1 Databases

  DB: D1Database

  // R2 Buckets

  BUCKET: R2Bucket

  // Durable Objects

  COUNTER: DurableObjectNamespace

  // Queues

  MY_QUEUE: Queue

}

const app = new Hono<{ Bindings: Bindings }>()

app.get('/config', (c) => {

  // Fully typed access

  const apiKey = c.env.API_KEY

  return c.json({ configured: !!apiKey })

})

export default app

wrangler.toml Configuration

name = "my-app"

main = "src/index.ts"

compatibility_date = "2024-01-01"

[vars]

API_KEY = "your-api-key"  # pragma: allowlist secret

[[kv_namespaces]]

binding = "MY_KV"

id = "your-kv-id"

[[d1_databases]]

binding = "DB"

database_name = "my-database"

database_id = "your-d1-id"

[[r2_buckets]]

binding = "BUCKET"

bucket_name = "my-bucket"

[[queues.producers]]

binding = "MY_QUEUE"

queue = "my-queue"

KV Storage

Basic Operations

type Bindings = {

  CACHE: KVNamespace

}

const app = new Hono<{ Bindings: Bindings }>()

// Get value

app.get('/cache/:key', async (c) => {

  const key = c.req.param('key')

  const value = await c.env.CACHE.get(key)

  if (!value) {

    return c.json({ error: 'Not found' }, 404)

  }

  return c.json({ key, value })

})

// Get JSON value

app.get('/cache/:key/json', async (c) => {

  const key = c.req.param('key')

  const value = await c.env.CACHE.get(key, 'json')

  return c.json({ key, value })

})

// Set value

app.put('/cache/:key', async (c) => {

  const key = c.req.param('key')

  const body = await c.req.json()

  await c.env.CACHE.put(key, JSON.stringify(body), {

    expirationTtl: 3600  // 1 hour

  })

  return c.json({ success: true })

})

// Delete value

app.delete('/cache/:key', async (c) => {

  const key = c.req.param('key')

  await c.env.CACHE.delete(key)

  return c.json({ success: true })

})

// List keys

app.get('/cache', async (c) => {

  const prefix = c.req.query('prefix') || ''

  const list = await c.env.CACHE.list({ prefix, limit: 100 })

  return c.json({ keys: list.keys })

})

KV with Metadata

interface UserMeta {

  createdAt: string

  role: string

}

app.put('/users/:id', async (c) => {

  const id = c.req.param('id')

  const user = await c.req.json()

  await c.env.CACHE.put(`user:${id}`, JSON.stringify(user), {

    metadata: {

      createdAt: new Date().toISOString(),

      role: user.role

    } as UserMeta

  })

  return c.json({ success: true })

})

app.get('/users/:id', async (c) => {

  const id = c.req.param('id')

  const { value, metadata } = await c.env.CACHE.getWithMetadata<UserMeta>(`user:${id}`, 'json')

  if (!value) {

    return c.json({ error: 'Not found' }, 404)

  }

  return c.json({ user: value, metadata })

})

D1 Database

Basic Queries

type Bindings = {

  DB: D1Database

}

const app = new Hono<{ Bindings: Bindings }>()

// Select all

app.get('/users', async (c) => {

  const { results } = await c.env.DB

    .prepare('SELECT * FROM users ORDER BY created_at DESC')

    .all()

  return c.json({ users: results })

})

// Select one

app.get('/users/:id', async (c) => {

  const id = c.req.param('id')

  const user = await c.env.DB

    .prepare('SELECT * FROM users WHERE id = ?')

    .bind(id)

    .first()

  if (!user) {

    return c.json({ error: 'Not found' }, 404)

  }

  return c.json({ user })

})

// Insert

app.post('/users', async (c) => {

  const { name, email } = await c.req.json()

  const result = await c.env.DB

    .prepare('INSERT INTO users (name, email) VALUES (?, ?)')

    .bind(name, email)

    .run()

  return c.json({

    success: result.success,

    id: result.meta.last_row_id

  }, 201)

})

// Update

app.put('/users/:id', async (c) => {

  const id = c.req.param('id')

  const { name, email } = await c.req.json()

  const result = await c.env.DB

    .prepare('UPDATE users SET name = ?, email = ? WHERE id = ?')

    .bind(name, email, id)

    .run()

  return c.json({ success: result.success })

})

// Delete

app.delete('/users/:id', async (c) => {

  const id = c.req.param('id')

  const result = await c.env.DB

    .prepare('DELETE FROM users WHERE id = ?')

    .bind(id)

    .run()

  return c.json({ success: result.success })

})

Batch Operations

app.post('/users/batch', async (c) => {

  const { users } = await c.req.json()

  const statements = users.map((user: { name: string; email: string }) =>

    c.env.DB

      .prepare('INSERT INTO users (name, email) VALUES (?, ?)')

      .bind(user.name, user.email)

  )

  const results = await c.env.DB.batch(statements)

  return c.json({

    success: results.every(r => r.success),

    count: results.length

  })

})

R2 Object Storage

type Bindings = {

  BUCKET: R2Bucket

}

const app = new Hono<{ Bindings: Bindings }>()

// Upload file

app.post('/files/:key', async (c) => {

  const key = c.req.param('key')

  const body = await c.req.arrayBuffer()

  const contentType = c.req.header('Content-Type') || 'application/octet-stream'

  await c.env.BUCKET.put(key, body, {

    httpMetadata: { contentType }

  })

  return c.json({ success: true, key })

})

// Download file

app.get('/files/:key', async (c) => {

  const key = c.req.param('key')

  const object = await c.env.BUCKET.get(key)

  if (!object) {

    return c.json({ error: 'Not found' }, 404)

  }

  const headers = new Headers()

  headers.set('Content-Type', object.httpMetadata?.contentType || 'application/octet-stream')

  headers.set('ETag', object.httpEtag)

  return new Response(object.body, { headers })

})

// Delete file

app.delete('/files/:key', async (c) => {

  const key = c.req.param('key')

  await c.env.BUCKET.delete(key)

  return c.json({ success: true })

})

// List files

app.get('/files', async (c) => {

  const prefix = c.req.query('prefix') || ''

  const list = await c.env.BUCKET.list({ prefix, limit: 100 })

  return c.json({

    objects: list.objects.map(obj => ({

      key: obj.key,

      size: obj.size,

      uploaded: obj.uploaded

    }))

  })

})

Durable Objects

Define Durable Object

// src/counter.ts

export class Counter {

  private state: DurableObjectState

  private value: number = 0

  constructor(state: DurableObjectState) {

    this.state = state

  }

  async fetch(request: Request): Promise<Response> {

    const url = new URL(request.url)

    // Load value from storage

    this.value = await this.state.storage.get('value') || 0

    switch (url.pathname) {

      case '/increment':

        this.value++

        await this.state.storage.put('value', this.value)

        return new Response(String(this.value))

      case '/decrement':

        this.value--

        await this.state.storage.put('value', this.value)

        return new Response(String(this.value))

      case '/value':

        return new Response(String(this.value))

      default:

        return new Response('Not found', { status: 404 })

    }

  }

}

Use in Hono

import { Hono } from 'hono'

type Bindings = {

  COUNTER: DurableObjectNamespace

}

const app = new Hono<{ Bindings: Bindings }>()

app.get('/counter/:name/increment', async (c) => {

  const name = c.req.param('name')

  const id = c.env.COUNTER.idFromName(name)

  const stub = c.env.COUNTER.get(id)

  const response = await stub.fetch('http://counter/increment')

  const value = await response.text()

  return c.json({ name, value: parseInt(value) })

})

app.get('/counter/:name', async (c) => {

  const name = c.req.param('name')

  const id = c.env.COUNTER.idFromName(name)

  const stub = c.env.COUNTER.get(id)

  const response = await stub.fetch('http://counter/value')

  const value = await response.text()

  return c.json({ name, value: parseInt(value) })

})

export default app

export { Counter }

wrangler.toml for Durable Objects

[[durable_objects.bindings]]

name = "COUNTER"

class_name = "Counter"

[[migrations]]

tag = "v1"

new_classes = ["Counter"]

Queues

Producer

type Bindings = {

  MY_QUEUE: Queue

}

const app = new Hono<{ Bindings: Bindings }>()

app.post('/tasks', async (c) => {

  const task = await c.req.json()

  await c.env.MY_QUEUE.send({

    type: 'process',

    data: task

  })

  return c.json({ queued: true })

})

// Batch send

app.post('/tasks/batch', async (c) => {

  const { tasks } = await c.req.json()

  await c.env.MY_QUEUE.sendBatch(

    tasks.map((task: any) => ({

      body: { type: 'process', data: task }

    }))

  )

  return c.json({ queued: tasks.length })

})

Consumer

export default {

  fetch: app.fetch,

  async queue(batch: MessageBatch, env: Bindings): Promise<void> {

    for (const message of batch.messages) {

      const { type, data } = message.body as { type: string; data: any }

      try {

        // Process message

        console.log(`Processing ${type}:`, data)

        message.ack()

      } catch (error) {

        message.retry()

      }

    }

  }

}

Static Assets

wrangler.toml

name = "my-app"

main = "src/index.ts"

compatibility_date = "2024-01-01"

# Serve static files from public directory

assets = { directory = "public" }

With Route Handler

import { Hono } from 'hono'

import { serveStatic } from 'hono/cloudflare-workers'

const app = new Hono()

// Serve static files

app.use('/static/*', serveStatic({ root: './' }))

// API routes

app.get('/api/hello', (c) => c.json({ hello: 'world' }))

export default app

Scheduled Events (Cron)

import { Hono } from 'hono'

const app = new Hono()

// Regular routes...

export default {

  fetch: app.fetch,

  async scheduled(

    event: ScheduledEvent,

    env: Bindings,

    ctx: ExecutionContext

  ): Promise<void> {

    switch (event.cron) {

      case '0 * * * *':  // Every hour

        await hourlyTask(env)

        break

      case '0 0 * * *':  // Daily at midnight

        await dailyTask(env)

        break

    }

  }

}

async function hourlyTask(env: Bindings) {

  console.log('Running hourly task')

}

async function dailyTask(env: Bindings) {

  console.log('Running daily task')

}

wrangler.toml for Cron

[triggers]

crons = ["0 * * * *", "0 0 * * *"]

Cloudflare Pages

pages/functions Directory

my-app/

├── public/              # Static assets

│   ├── index.html

│   └── styles.css

└── functions/

    └── [[path]].ts      # Catch-all function

Catch-All Handler

// functions/[[path]].ts

import { Hono } from 'hono'

import { handle } from 'hono/cloudflare-pages'

const app = new Hono().basePath('/api')

app.get('/hello', (c) => c.json({ hello: 'world' }))

app.post('/echo', async (c) => c.json(await c.req.json()))

export const onRequest = handle(app)

Middleware with Bindings

import { createMiddleware } from 'hono/factory'

type Bindings = {

  API_KEY: string

}

// Access env in middleware

const authMiddleware = createMiddleware<{ Bindings: Bindings }>(

  async (c, next) => {

    // Don't access env at module level - access in handler!

    const apiKey = c.req.header('X-API-Key')

    if (apiKey !== c.env.API_KEY) {

      return c.json({ error: 'Unauthorized' }, 401)

    }

    await next()

  }

)

app.use('/api/*', authMiddleware)

Quick Reference

Bindings Types

type Bindings = {

  // Variables

  MY_VAR: string

  // KV

  MY_KV: KVNamespace

  // D1

  DB: D1Database

  // R2

  BUCKET: R2Bucket

  // Durable Objects

  MY_DO: DurableObjectNamespace

  // Queues

  MY_QUEUE: Queue

  // Service Bindings

  OTHER_WORKER: Fetcher

}

Common Commands

# Local development

npx wrangler dev

# Deploy

npx wrangler deploy

# Create D1 database

npx wrangler d1 create my-database

# Execute D1 SQL

npx wrangler d1 execute my-database --file=schema.sql

# Create KV namespace

npx wrangler kv:namespace create MY_KV

# Create R2 bucket

npx wrangler r2 bucket create my-bucket

# Tail logs

npx wrangler tail

Related Skills

• hono-core - Framework fundamentals

• hono-middleware - Middleware patterns

• hono-testing - Testing with mocked bindings

Version: Hono 4.x, Wrangler 3.x

Last Updated: January 2025

License: MIT