Hono: il Web Framework Ultraleggero per API Moderne

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 dev

Il 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 app

Nota 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 app

Il 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 app

Scrivere 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 app

Il 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 --local

Il 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 app

Il 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 --remote per 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-openapi per 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.

Condividi

Articoli Recenti

Categorie popolari