Hono: il Web Framework Ultraleggero per API Moderne
Perché Hono nel 2026
Il panorama dei web framework JavaScript è cambiato radicalmente. Negli ultimi anni siamo passati da Express.js — uno standard de facto ma nato in un’epoca in cui l’Edge computing non esisteva — a soluzioni pensate nativamente per runtime moderni come Cloudflare Workers, Bun e Deno. Hono è la risposta più convincente a questa esigenza: un framework TypeScript-first, ultraleggero (meno di 13 KB minified), senza dipendenze esterne e con un’API deliberatamente semplice.
Se stai costruendo API REST, gateway BFF o microservizi che devono girare ai margini della rete con latenze sotto i 10ms, Hono è probabilmente il tool più adatto che puoi adottare oggi. Il suo design si ispira a Fastify e Express per la semplicità dell’interfaccia, ma abbandona completamente Node.js-isms come il concetto di req/res basato su stream, abbracciando invece la Fetch API standard (Request/Response) che funziona ugualmente su ogni runtime moderno.
In questo articolo vedremo come iniziare con Hono, come strutturare un’API reale con middleware, validazione e routing, e come fare il deploy su Cloudflare Workers. Se hai già lavorato con tRPC per API type-safe, troverai in Hono un complemento ideale per i casi d’uso REST classici.
Installazione e Primo Server in 5 Minuti
Creare un progetto Hono è immediato. Il CLI ufficiale scaffolda un progetto pronto con il runtime target di tua scelta:
# Crea nuovo progetto Hono (interattivo)
npm create hono@latest my-api
# Oppure con Bun (consigliato per sviluppo locale)
bun create hono@latest my-api
# Seleziona il runtime: cloudflare-workers | bun | deno | node | vercel
cd my-api
bun install
bun devIl file di partenza src/index.ts generato dal CLI mostra già la filosofia di Hono. L’istanza del framework si crea con new Hono(), le route si definiscono con metodi chainabili, e l’export default è un oggetto con il handler fetch — compatibile 1:1 con la Service Worker API usata da Cloudflare Workers e con il runtime Bun:
import { Hono } from 'hono'
const app = new Hono()
// Route base
app.get('/', (c) => {
return c.text('Hello from Hono!')
})
// JSON response tipizzato
app.get('/health', (c) => {
return c.json({
status: 'ok',
timestamp: new Date().toISOString(),
runtime: typeof Bun !== 'undefined' ? 'bun' : 'other',
})
})
// Route con parametri
app.get('/users/:id', async (c) => {
const id = c.req.param('id')
// c.req.valid('param') per validazione con Zod (vedi dopo)
return c.json({ id, name: 'Mario Rossi' })
})
export default appNota il contesto c (Context): è il cuore dell’API di Hono. Racchiude request, response, variabili e helper di rendering. Non hai bisogno di importare niente di extra per c.json(), c.text(), c.html() o c.redirect().
Routing Avanzato e Subrouter
Hono supporta routing gerarchico con app.route(), il che ti permette di organizzare un’API grande in moduli separati senza sporcare il file principale. Questo pattern scala bene e si integra perfettamente con la struttura dei progetti TypeScript moderni.
// routes/posts.ts
import { Hono } from 'hono'
type Variables = {
userId: string
}
const posts = new Hono<{ Variables: Variables }>()
posts.get('/', async (c) => {
const userId = c.get('userId') // valorizzato dal middleware auth
const db = c.env.DB // Cloudflare D1 binding (example)
const result = await db
.prepare('SELECT * FROM posts WHERE author_id = ? ORDER BY created_at DESC LIMIT 20')
.bind(userId)
.all()
return c.json({ posts: result.results })
})
posts.post('/', async (c) => {
const body = await c.req.json<{ title: string; content: string }>()
if (!body.title || body.title.length < 3) {
return c.json({ error: 'Titolo troppo corto' }, 400)
}
// inserimento DB...
return c.json({ id: crypto.randomUUID(), ...body }, 201)
})
posts.delete('/:id', async (c) => {
const id = c.req.param('id')
// logica eliminazione...
return c.body(null, 204)
})
export { posts }
// index.ts — montaggio subrouter
import { Hono } from 'hono'
import { posts } from './routes/posts'
import { authMiddleware } from './middleware/auth'
const app = new Hono()
// Middleware globale solo per /api/*
app.use('/api/*', authMiddleware)
// Mounting del subrouter
app.route('/api/posts', posts)
export default appIl typing generico Hono<{ Variables: Variables }> è uno dei punti di forza di Hono: puoi passare tipi personalizzati per variabili di contesto, binding Cloudflare ed env, mantenendo la type-safety end-to-end — qualcosa che apprezzi ancora di più se hai già usato Drizzle ORM per le query type-safe.
Middleware: Auth, CORS e Logger
Hono viene con una collezione di middleware ufficiali pronti all’uso (hono/middleware). Non devi installare pacchetti separati per le funzionalità più comuni:
- cors — configura Cross-Origin Resource Sharing con options granulari
- logger — log delle richieste in formato colorato (dev) o strutturato (prod)
- jwt — verifica JWT con supporto a HS256/RS256 senza dipendenze
- basicAuth — autenticazione HTTP Basic per endpoint di amministrazione
- cache — integrazione con la Cache API di Cloudflare Workers
- compress — compressione gzip/brotli automatica delle risposte
import { Hono } from 'hono'
import { cors } from 'hono/cors'
import { logger } from 'hono/logger'
import { jwt } from 'hono/jwt'
import { prettyJSON } from 'hono/pretty-json'
import { secureHeaders } from 'hono/secure-headers'
const app = new Hono()
// Middleware globali
app.use('*', logger())
app.use('*', secureHeaders())
app.use('*', prettyJSON())
// CORS configurato per il tuo frontend
app.use('/api/*', cors({
origin: ['https://tuodominio.com', 'http://localhost:3000'],
allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
allowHeaders: ['Content-Type', 'Authorization'],
maxAge: 86400,
}))
// JWT middleware solo per route protette
const jwtMiddleware = jwt({
secret: 'tuo-secret-jwt', // in prod: c.env.JWT_SECRET
})
app.use('/api/admin/*', jwtMiddleware)
// Route pubblica
app.get('/api/public', (c) => c.json({ message: 'Accessibile a tutti' }))
// Route protetta - c.get('jwtPayload') disponibile dopo jwt()
app.get('/api/admin/dashboard', (c) => {
const payload = c.get('jwtPayload')
return c.json({
message: `Benvenuto, ${payload.sub}`,
role: payload.role,
})
})
// Middleware custom: timing e request ID
app.use('*', async (c, next) => {
const start = Date.now()
c.set('requestId', crypto.randomUUID())
await next()
const ms = Date.now() - start
c.header('X-Response-Time', `${ms}ms`)
c.header('X-Request-Id', c.get('requestId'))
})
export default appScrivere middleware custom in Hono è identico a Express: una funzione asincrona che riceve (c, next) e chiama await next() per passare il controllo al handler successivo. La differenza sostanziale è che tutto rimane dentro il tipo Context senza inquinare oggetti req/res con proprietà arbitrarie.
Validazione con Zod e zod-validator
La validazione degli input è critica in qualsiasi API di produzione. Hono si integra perfettamente con Zod tramite il validator middleware ufficiale. Questo approccio garantisce che i dati in arrivo siano già validati e tipizzati quando raggiungono il tuo handler — esattamente come descritto nella guida a Zod per TypeScript:
import { Hono } from 'hono'
import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'
const app = new Hono()
// Schema di validazione
const createUserSchema = z.object({
name: z.string().min(2).max(100),
email: z.string().email(),
role: z.enum(['admin', 'editor', 'viewer']).default('viewer'),
metadata: z.record(z.string()).optional(),
})
const querySchema = z.object({
page: z.coerce.number().min(1).default(1),
limit: z.coerce.number().min(1).max(100).default(20),
search: z.string().optional(),
})
// POST con validazione del body
app.post(
'/users',
zValidator('json', createUserSchema, (result, c) => {
if (!result.success) {
return c.json(
{
error: 'Dati non validi',
issues: result.error.issues.map((i) => ({
field: i.path.join('.'),
message: i.message,
})),
},
422
)
}
}),
async (c) => {
// body è automaticamente tipizzato come z.infer<typeof createUserSchema>
const body = c.req.valid('json')
console.log(body.email) // string, garantito
console.log(body.role) // 'admin' | 'editor' | 'viewer'
// logica creazione utente...
return c.json({ id: crypto.randomUUID(), ...body }, 201)
}
)
// GET con validazione dei query params
app.get('/users', zValidator('query', querySchema), async (c) => {
const { page, limit, search } = c.req.valid('query')
// page e limit sono already number (z.coerce.number())
const offset = (page - 1) * limit
return c.json({
data: [], // risultati dal DB
meta: { page, limit, offset, search },
})
})
export default appIl pacchetto @hono/zod-validator si installa separatamente (bun add @hono/zod-validator zod). Quando la validazione fallisce, il callback personalizzato ti permette di formattare l’errore esattamente come vuoi — una feature che manca in molti altri framework e che diventa fondamentale quando stai costruendo un’API consumata da un’app che potrebbe integrare anche un pipeline di code review automatico sulle PR.
Deploy su Cloudflare Workers: Edge Computing Reale
Il deploy di Hono su Cloudflare Workers è il caso d’uso più potente e quello per cui il framework è stato originariamente ottimizzato. Con Wrangler (la CLI di Cloudflare) il processo richiede pochi minuti:
# Installa Wrangler
npm install -g wrangler
# Login a Cloudflare
wrangler login
# Deploy (dalla root del progetto Hono)
wrangler deploy
# Deploy con variabili d'ambiente
wrangler secret put JWT_SECRET
wrangler secret put DATABASE_URL
# Preview locale (simula il runtime Workers)
wrangler dev --localIl file wrangler.toml generato dal CLI Hono configura già tutto il necessario. Puoi aggiungere binding a servizi Cloudflare come D1 (database SQLite globale), R2 (object storage), KV (key-value store) e Queues direttamente nel file di configurazione. I binding diventano disponibili in c.env con piena type-safety se dichiari il tipo Bindings nel generic di Hono:
// types.ts — definizione dei binding Cloudflare
type Bindings = {
DB: D1Database // Cloudflare D1
BUCKET: R2Bucket // Cloudflare R2
CACHE: KVNamespace // Cloudflare KV
JWT_SECRET: string // secret variable
ENVIRONMENT: string // plain variable
}
type Variables = {
userId: string
jwtPayload: { sub: string; role: string; exp: number }
}
// app tipizzata completamente
const app = new Hono<{ Bindings: Bindings; Variables: Variables }>()
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: 'File non trovato' }, 404)
}
return new Response(object.body, {
headers: {
'Content-Type': object.httpMetadata?.contentType ?? 'application/octet-stream',
'Cache-Control': 'public, max-age=31536000',
},
})
})
app.post('/cache/:key', async (c) => {
const key = c.req.param('key')
const value = await c.req.text()
await c.env.CACHE.put(key, value, { expirationTtl: 3600 })
return c.json({ cached: true, key, ttl: 3600 })
})
export default appIl risultato è un’API che gira su oltre 300 edge location Cloudflare nel mondo, con cold start praticamente zero (Hono è abbastanza leggero da avviarsi in meno di 1ms) e un costo operativo irrisorio. Per confronto, un’API Express su un server tradizionale richiederebbe istanze always-on, load balancer e molto più overhead di gestione infrastrutturale — un costo che per i freelance e i team piccoli incide in modo significativo, come discusso nell’articolo su stack zero-cost per lanciare un SaaS.
Testing e RPC Client Type-Safe
Una funzionalità meno nota ma estremamente potente di Hono è il RPC Client: puoi esportare il tipo della tua app e usarlo sul client per chiamare le API con piena type-safety, senza generatori di codice o schema separati. Funziona in modo simile a tRPC, ma con il vantaggio di rimanere nel paradigma REST standard:
// server/api.ts
import { Hono } from 'hono'
import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'
const api = new Hono()
.get('/posts', async (c) => {
return c.json({ posts: [{ id: '1', title: 'Hono è fantastico' }] })
})
.post(
'/posts',
zValidator('json', z.object({ title: z.string().min(1), body: z.string() })),
async (c) => {
const { title, body } = c.req.valid('json')
return c.json({ id: crypto.randomUUID(), title, body }, 201)
}
)
export type ApiType = typeof api
export default api
// client/index.ts (frontend React, Next.js, ecc.)
import { hc } from 'hono/client'
import type { ApiType } from '../server/api'
// Crea il client con piena type-safety
const client = hc<ApiType>('http://localhost:8787')
// Chiamata GET — tipo inferito automaticamente
const res = await client.posts.$get()
const data = await res.json()
// data.posts è tipizzato: Array<{ id: string; title: string }>
// Chiamata POST — il corpo è validato a compile time
const createRes = await client.posts.$post({
json: { title: 'Nuovo Post', body: 'Contenuto...' },
})
// Errore TypeScript se title è mancante o body non è string
// Testing con hono/testing (no server necessario)
import { testClient } from 'hono/testing'
import api from '../server/api'
test('GET /posts restituisce array', async () => {
const client = testClient(api)
const res = await client.posts.$get()
expect(res.status).toBe(200)
const body = await res.json()
expect(Array.isArray(body.posts)).toBe(true)
})
test('POST /posts crea un post', async () => {
const client = testClient(api)
const res = await client.posts.$post({
json: { title: 'Test Post', body: 'Body del post' },
})
expect(res.status).toBe(201)
const body = await res.json()
expect(body.title).toBe('Test Post')
})Il testClient di Hono esegue i test direttamente in memoria, senza avviare un server HTTP. Questo rende la test suite estremamente rapida e adatta a pipeline CI/CD — esattamente il tipo di automazione che si integra bene con workflow come quelli descritti in Claude API per automatizzare il workflow da developer.
FAQ e Domande Frequenti
Hono sostituisce Express.js?
Dipende dal contesto. Se stai costruendo una nuova API da zero e non hai vincoli legacy, Hono è quasi sempre la scelta migliore: è più veloce, type-safe per design, e funziona su tutti i runtime moderni senza modifiche. Express rimane valido se hai un’applicazione Node.js consolidata con molti middleware di terze parti che non hanno ancora equivalenti in Hono — ma l’ecosistema di Hono sta crescendo velocemente. Per nuovi progetti, specialmente su Edge computing, la risposta è sì: Hono sostituisce Express con vantaggi concreti.
Hono funziona con Node.js?
Sì, Hono funziona su Node.js tramite il pacchetto @hono/node-server. Basta wrappare la tua app Hono con serve(app) e gira su un server HTTP Node.js standard. Tuttavia il vero punto di forza di Hono è sui runtime Edge: Cloudflare Workers, Bun, Deno e Vercel Edge Functions. Su Node.js funziona, ma perdi i vantaggi specifici del runtime ultraleggero. Se il tuo unico target è Node.js, Fastify potrebbe essere una scelta più matura per la quantità di plugin disponibili.
Come gestire i file statici con Hono?
Hono include il middleware serveStatic per servire file statici, ma l’implementazione varia per runtime. Su Cloudflare Workers usa i binding R2 o Workers Sites. Su Bun e Node.js usa il filesystem locale. In generale, per applicazioni full-stack con molti asset statici, è meglio affidare i file a un CDN (Cloudflare Pages, Vercel) e usare Hono solo per l’API. Il pattern ibrido — frontend su CDN, API su Workers — è quello che sfrutta meglio l’architettura Edge.
Hono si integra con database come Supabase o Drizzle?
Sì, senza problemi. Hono è agnostico rispetto al layer dati: puoi usare Drizzle ORM con un database Postgres/MySQL/D1, Supabase client, Prisma (con alcune limitazioni sull’Edge), o qualsiasi libreria che supporti il runtime target. La combinazione più popolare nel 2026 è Hono + Drizzle ORM + Cloudflare D1 per API completamente Edge, oppure Hono + Supabase per chi vuole un backend managed. Consulta la guida a Supabase nel 2026 per dettagli sull’integrazione con client JavaScript moderni.
Conclusione
Hono rappresenta il punto di convergenza tra semplicità d’uso, performance native e compatibilità universale con i runtime moderni. Non è un’astrazione complessa: è un layer sottile che ti dà routing, middleware e context management con zero overhead, lasciandoti libero di usare le API native del platform di destinazione.
Se stai costruendo API REST, microservizi Edge, BFF per frontend React/Next.js o semplicemente vuoi rimpiazzare Express con qualcosa di più moderno e type-safe, Hono è la scelta più solida del 2026. Il suo RPC client lo rende addirittura competitivo con tRPC per i casi d’uso full-stack, mantenendo al contempo la compatibilità REST standard con qualsiasi altro consumer.
Inizia con bun create hono@latest, scegli Cloudflare Workers come target, e avrai un’API in produzione globale in meno di 30 minuti.
Suggerimenti e Risorse
🔧 Tool: Usa
wrangler dev --remoteper testare la tua app Hono direttamente sull’infrastruttura Cloudflare durante lo sviluppo — simula i binding reali come D1 e R2 senza deploy.
💡 Pro tip: Combina Hono con
@hono/zod-openapiper generare automaticamente la documentazione OpenAPI/Swagger dai tuoi schema Zod. Zero lavoro duplicato: il tuo codice TypeScript diventa la fonte di verità per la documentazione API.
🎯 Strategia: Per un’API che deve gestire migliaia di richieste al secondo con costi minimi, la combinazione Hono + Cloudflare Workers + D1 + R2 ti dà scalabilità globale automatica senza gestire infrastruttura. Il free tier di Cloudflare Workers copre 100.000 richieste al giorno — ideale per validare un Micro SaaS prima di investire in server dedicati.

