Hono framework TypeScript en production : guide complet 2026

L’API REST d’une PME de logistique à Abidjan tournait sur Express 4 avec 35 endpoints. À chaque pic de commandes le matin (entre 7 h et 9 h), la latence p95 dépassait 800 ms et l’équipe ajoutait des serveurs. Migration vers Hono en deux semaines : même code métier, même base PostgreSQL, mais le binaire est 12 fois plus léger, démarre en 80 ms au lieu de 1,2 seconde, et le p95 est tombé à 95 ms sur le même VPS Hetzner CX22. Hono est devenu en 2026 le framework web TypeScript le plus pragmatique pour les API et les BFF des SaaS ouest-africains. Ce pilier couvre l’architecture, le routing, les middlewares, le déploiement multi-runtime, et la comparaison honnête avec Express, Fastify et Elysia. Pour le tutoriel spécifique Bun + Hono, voir l’article dédié Bun + Hono : construire une API REST type-safe en 2026 qui complète ce guide.

Pourquoi Hono en 2026

Hono est un framework web TypeScript-first publié en 2022 et devenu mature en 2024-2025. Trois caractéristiques expliquent son adoption : portabilité multi-runtime (Node, Deno, Bun, Cloudflare Workers, Vercel Edge, AWS Lambda — le même code tourne partout), typage strict de bout en bout (les paramètres de route, les bodies validés, les réponses sont typés sans configuration), et taille de bundle minimale (le core fait moins de 14 Ko gzippé, un ordre de grandeur en dessous d’Express + middlewares classiques). Pour un service backend déployé sur un VPS Hetzner CX22 ou en edge sur Cloudflare Workers, l’écart de performance par rapport à Express est mesurable et confirmé sur les benchmarks publics du dépôt officiel.

Le quatrième argument, plus subjectif mais important au quotidien : l’API du framework est cohérente et minimale. Là où Express demande de connaître les conventions des middlewares, les helpers res.send vs res.json, et la subtile différence entre app.use et app.all, Hono propose une API uniforme inspirée du standard Web Fetch (Request et Response). Un développeur qui maîtrise fetch côté client est productif en deux heures côté serveur.

Installation et premier serveur

Hono fournit un générateur officiel qui scaffolde un projet pour le runtime cible :

npm create hono@latest mon-api
# Choisir : nodejs (ou cloudflare-workers, bun, deno-deploy)

Le projet généré tient en 30 lignes et compile en TypeScript pur. Exemple Node :

// src/index.ts
import { Hono } from 'hono';
import { serve } from '@hono/node-server';

const app = new Hono();

app.get('/', (c) => c.text('Hello Dakar !'));
app.get('/api/users/:id', (c) => c.json({ id: c.req.param('id'), nom: 'Aïssatou' }));

serve({ fetch: app.fetch, port: 3000 }, (info) => {
  console.log('Serveur sur http://localhost:' + info.port);
});

Ce code unique tourne sans modification sous Bun (avec Bun.serve({ fetch: app.fetch })), sous Deno (Deno.serve(app.fetch)), et sous Cloudflare Workers (export default { fetch: app.fetch }). Cette portabilité est l’argument central : on choisit le runtime selon les contraintes (latence edge, coût VPS, écosystème npm) sans réécrire la logique métier.

Routing et paramètres typés

Le routing Hono est familier mais avec un avantage : les paramètres d’URL sont typés statiquement. Le compilateur sait qu’un endpoint /api/clients/:id/commandes/:cmd reçoit deux paramètres nommés, et toute typo dans c.req.param('idd') est signalée à la compilation.

app.get('/api/clients/:id/commandes/:cmd', (c) => {
  const { id, cmd } = c.req.param();
  return c.json({ client: id, commande: cmd });
});

// Wildcards
app.get('/files/*', (c) => c.text(c.req.path));

// Regex sur paramètre
app.get('/api/produits/:slug{[a-z0-9-]+}', (c) => c.text(c.req.param('slug')));

Pour grouper des routes liées sous un préfixe, on utilise app.route() ou un sous-router :

const adminApi = new Hono();
adminApi.get('/stats', (c) => c.json({ ventes: 12500 }));
adminApi.post('/users', async (c) => { const body = await c.req.json(); return c.json({ ok: true }); });

app.route('/admin', adminApi);

Middleware : logger, CORS, auth, rate limit

Les middlewares Hono suivent le pattern Koa-like : on appelle await next() au milieu, on peut modifier la réponse après. La librairie de base fournit les middlewares essentiels prêts à l’emploi.

import { logger } from 'hono/logger';
import { cors } from 'hono/cors';
import { secureHeaders } from 'hono/secure-headers';
import { jwt } from 'hono/jwt';

app.use('*', logger());
app.use('*', secureHeaders());
app.use('/api/*', cors({ origin: ['https://example.sn'], credentials: true }));
app.use('/api/admin/*', jwt({ secret: process.env.JWT_SECRET! }));

Pour un middleware custom de rate limit par IP :

const compteurs = new Map();
app.use('/api/*', async (c, next) => {
  const ip = c.req.header('x-forwarded-for') || 'inconnu';
  const now = Date.now();
  const e = compteurs.get(ip) ?? { count: 0, reset: now + 60_000 };
  if (now > e.reset) { e.count = 0; e.reset = now + 60_000; }
  e.count++;
  compteurs.set(ip, e);
  if (e.count > 100) return c.json({ erreur: 'Rate limit' }, 429);
  await next();
});

Validation typée avec Zod

Le helper @hono/zod-validator intègre Zod en deux lignes et fournit la validation de body, query, params, headers avec auto-typage des handlers.

import { zValidator } from '@hono/zod-validator';
import { z } from 'zod';

const schema = z.object({
  nom: z.string().min(2),
  telephone: z.string().regex(/^\+?[0-9 -]{8,15}$/),
  pays: z.enum(['SN','CI','ML','BF'])
});

app.post('/api/inscriptions', zValidator('json', schema), (c) => {
  const data = c.req.valid('json');
  return c.json({ id: 'usr_123', ...data }, 201);
});

Cette double sécurité (validation runtime + typage compile) supprime un pan entier de bugs liés aux entrées mal formées. Pour un endpoint de paiement Wave qui doit absolument valider montant et numéro avant tout appel API tiers, c’est indispensable.

Mode RPC : client typé partagé

Hono propose un mode RPC unique : exporter le type du serveur permet de créer un client TypeScript qui connaît toutes les routes, leurs paramètres et leurs réponses. C’est l’équivalent tRPC sans les contraintes de procédures.

// server.ts
const route = app
  .get('/api/users/:id', (c) => c.json({ id: c.req.param('id'), nom: 'Aïssatou' }))
  .post('/api/users', zValidator('json', schema), (c) => c.json({ ok: true }, 201));
export type AppType = typeof route;

// client.ts
import { hc } from 'hono/client';
import type { AppType } from './server';

const client = hc<AppType>('https://api.example.sn');
const r = await client.api.users[':id'].$get({ param: { id: '123' } });
const user = await r.json();

Pour les SaaS qui partagent du code entre front SvelteKit et back Hono dans un monorepo, ce pattern remplace la swagger-codegen ou les schémas dupliqués. La cohérence des types est garantie au build.

Déploiement multi-runtime : forces et limites

Hono brille parce qu’il fonctionne sur six runtimes principaux. Choisir le bon dépend des contraintes du projet.

Pour la majorité des SaaS B2B ouest-africains, Hetzner + Node ou Hetzner + Bun reste le meilleur compromis coût/contrôle. Cloudflare Workers s’impose dès qu’on cible une audience africaine large et qu’on veut une latence sub-100 ms depuis Lagos ou Accra grâce au PoP local.

Comparatif Express, Fastify, Elysia, Hono

Le marché TypeScript serveur compte quatre frameworks crédibles en 2026. Chacun a sa zone de pertinence :

• Express 5 reste le plus déployé, mais son API datée et l’absence de typage natif le pénalisent. Préférer Hono pour les nouveaux projets.
• Fastify 5 est performant et bien typé via TypeBox/Zod. Adapté aux APIs Node-only à forte charge. Hono fait jeu égal avec un avantage de portabilité multi-runtime.
• Elysia (équivalent Bun) est plus rapide brut mais lié à Bun. Si le projet est Bun-only, Elysia mérite considération ; sinon Hono est plus polyvalent.
• Hono gagne sur la portabilité, le mode RPC, et la cohérence d’API entre runtimes. C’est notre choix par défaut pour 2026.

Adaptation au contexte ouest-africain

Trois leviers spécifiques. Premièrement, le mode Cloudflare Workers donne un avantage net : le PoP de Lagos répond en moins de 50 ms à un client basé à Cocody ou Plateau, là où un VPS européen réclame 100 à 180 ms. Pour les API très fréquentes (tableaux de bord temps-réel, autocomplete), c’est sensible. Deuxièmement, la frugalité du bundle Hono permet de tenir un service complet (Hono + Drizzle + auth maison) dans la limite 1 Mo des Workers — chose impossible avec Express. Troisièmement, le mode Hetzner FRA1 + Node + Hono à 5 €/mois sert plusieurs milliers d’utilisateurs : pour une fintech qui démarre à Bamako avec un budget serré, c’est l’option la plus pragmatique avant de passer à l’edge.

Côté paiement Wave, Orange Money, Free Money : les SDK officiels (ou les wrappers communautaires) fonctionnent sans adaptation particulière sous Hono. La validation Zod sécurise les webhooks entrants, la signature HMAC se vérifie dans un middleware dédié, et le typage RPC permet au front (SvelteKit, Next ou Vue) d’appeler les endpoints sans duplication de schéma. Voir le tutoriel satellite « Hono + Wave/Orange Money : webhooks signés » pour le pattern complet.

Sécurité applicative et bonnes pratiques

Une API en production demande une discipline systématique. Trois axes à activer dès le premier jour. Sanitisation des entrées : Zod valide la forme, mais pour les chaînes destinées à être affichées dans une UI HTML, on échappe systématiquement avec une lib comme dompurify côté client ou sanitize-html côté serveur. Secrets et variables d’environnement : utiliser env de Hono qui abstrait la source (Cloudflare bindings, process.env Node, Bun.env). Ne jamais commiter de .env ni de clés. CORS strict : autoriser explicitement les domaines clients, pas *. Pour un SaaS multi-tenant, lister dynamiquement les origines depuis la base.

Côté logs et observabilité, on intègre Pino ou Winston en middleware custom et on agrège vers un service comme Better Stack, Axiom ou simplement vers Loki sur un VPS dédié. Les requêtes lentes (> 500 ms) sont logguées avec leur trace pour diagnostic. Les erreurs 5xx déclenchent une alerte Telegram immédiate via webhook.

Erreurs fréquentes à éviter

FAQ

Hono peut-il remplacer Express dans un projet existant ?
Oui. La migration se fait route par route en gardant les deux frameworks en parallèle derrière un reverse proxy ou via app.mount(). La majorité des middlewares Express ont un équivalent Hono direct ou une alternative communautaire.

Quel runtime choisir entre Bun et Node pour Hono ?
Bun gagne sur les performances brutes (cold start, throughput) mais son écosystème npm a encore quelques angles morts. Pour 2026, Node 22 LTS reste le choix sûr en production sauf besoin spécifique de performance brute. Pour les détails, voir Bun vs Node.js : benchmarks réels 2026.

Hono fonctionne-t-il avec Drizzle ORM ?
Oui parfaitement. Drizzle est runtime-agnostique et s’intègre dans n’importe quel handler Hono. Pour PostgreSQL sur Hetzner, on utilise le driver postgres-js. Sur Cloudflare Workers, on utilise Neon, Turso ou Cloudflare D1 selon la base.

Comment streamer une réponse SSE ou WebSocket ?
SSE via c.body(stream) avec un ReadableStream standard. WebSockets disponibles via @hono/node-ws sur Node, et nativement sur Cloudflare Workers via les Durable Objects.

Le typage RPC supporte-t-il les uploads de fichiers ?
Oui via c.req.parseBody() qui retourne un objet avec les champs et fichiers. Le typage est moins fin pour les fichiers (type File du DOM) mais reste utilisable.

Existe-t-il un panneau admin auto-généré ?
Pas dans Hono lui-même. Pour un panneau admin minimal, on utilise un front SvelteKit séparé qui consomme l’API via le client RPC.

Pour aller plus loin

Tutoriels du cluster Hono :

• Déployer Hono sur Cloudflare Workers : edge global pour l’Afrique
• Authentification JWT avec Hono : access et refresh tokens sécurisés
• Hono + Wave et Orange Money : webhooks signés et idempotence
• Mode RPC Hono avec SvelteKit dans un monorepo

Articles connexes :

• Bun + Hono : construire une API REST type-safe en 2026
• Svelte 5 et SvelteKit 2 en production
• Hetzner Cloud depuis l’Afrique de l’Ouest

Documentation officielle :

• hono.dev
• GitHub honojs/hono

Benchmarks réels et performance

Les chiffres avancés en début d’article s’appuient sur des mesures cohérentes avec les benchmarks publics de l’écosystème. Sur le benchmark officiel Hono (méthodologie disponible dans le dépôt), Hono traite environ 230 000 requêtes par seconde sur Bun et 165 000 sur Node 22, contre 88 000 pour Express 4 dans la même configuration matérielle. Pour un cas d’usage réel — API REST avec validation Zod, requête PostgreSQL simple, logging — les performances pratiques sont plus modestes mais l’écart se maintient : on observe typiquement un facteur 2 à 4 entre Hono et Express sur le même VPS Hetzner CX22.

L’impact business est concret. Sur un endpoint d’autocomplete appelé 50 fois par session utilisateur, passer de 60 ms à 18 ms en p50 transforme l’expérience perçue à Cocody ou Plateau, où la latence réseau ajoute déjà 100-150 ms incompressibles. Sur les pics de charge matinaux d’une fintech à Dakar (entre 7 h et 9 h), le serveur Hono tient là où Express déclenche un autoscaling coûteux. Le coût mensuel d’infrastructure tombe de 60 à 80 % dans plusieurs des projets que nous avons accompagnés.

Une métrique souvent négligée : la mémoire. Un processus Hono sur Node 22 consomme 60 à 80 Mo au repos contre 140-180 Mo pour Express avec un set similaire de middlewares. Sur un VPS CX22 (4 Go RAM), cette frugalité libère de la mémoire pour PostgreSQL, Redis ou un autre service co-hébergé — économie supplémentaire qui évite de monter en gamme.

Stack complète exemple : Hono + Drizzle + auth

Voici un exemple de stack production pragmatique pour une API SaaS B2B ouest-africaine. La structure de projet est minimale, sans abstraction inutile, lisible par un nouveau développeur en moins d’une heure.

src/
  index.ts            # Bootstrap Hono, middlewares globaux
  routes/
    auth.ts           # /api/auth/login, /api/auth/refresh, /api/auth/me
    clients.ts        # CRUD clients
    factures.ts       # CRUD factures
    paiements.ts      # Webhooks Wave et Orange Money
  middleware/
    requireAuth.ts    # Vérifie JWT + charge user
    requireAdmin.ts   # Vérifie rôle admin
  db/
    schema.ts         # Schémas Drizzle (clients, factures, sessions)
    client.ts         # Pool postgres-js + drizzle()
  lib/
    hash.ts           # Argon2id wrapper
    jwt.ts            # Signing/verification
    audit.ts          # Log d'audit en base
.env                  # Variables d'environnement (jamais commitées)

Le fichier index.ts compose les sous-routers et applique les middlewares globaux. Les routes sont déclarées dans des fichiers séparés et montées via app.route('/api/clients', clientsRouter). Cette architecture supporte une dizaine de développeurs travaillant en parallèle sur des modules distincts sans conflits Git constants.

Drizzle ORM apporte le typage strict des requêtes SQL : les colonnes inexistantes sont signalées à la compilation, les jointures sont typées, et les migrations versionnées via drizzle-kit. Pour les agences ouest-africaines qui livrent à plusieurs clients, ce typage évite les bugs de production où une colonne renommée n’a pas été propagée à tous les endroits du code.

Migration depuis Express : plan en 4 semaines

Pour une équipe qui maintient une API Express en production et veut migrer vers Hono sans gel des features, voici un plan testé sur deux projets clients (un à Dakar pour une fintech, un à Abidjan pour une plateforme logistique). L’approche est itérative et n’introduit jamais de régression.

Semaine 1 — POC et benchmark. Forker un module isolé (par exemple les endpoints publics de catalogue) et le réécrire en Hono dans une branche dédiée. Lancer les benchmarks comparatifs (k6 ou autocannon). Valider que le comportement fonctionnel est identique, pas seulement plus rapide.

Semaine 2 — Coexistence par préfixe d’URL. Configurer un reverse proxy (Caddy ou nginx) qui route /api/v2/* vers le nouveau serveur Hono et le reste vers l’ancien Express. L’authentification est partagée via un cookie de session signé ou un JWT centralisé. Aucun client mobile ou web n’est cassé.

Semaine 3 — Migration des endpoints à fort trafic. Réécrire les 5-10 endpoints les plus appelés (typiquement liste produits, recherche, profil utilisateur). Le gain de latence est immédiat et visible dans les métriques Datadog ou Better Stack.

Semaine 4 — Migration des endpoints transactionnels. Plus délicat : les paiements, créations de comptes, traitement de webhooks. On migre par batch, on monitore les erreurs, on garde l’ancien code prêt en rollback derrière un feature flag.

Au-delà, les endpoints internes peu utilisés (admin, exports CSV) se migrent au fil de l’eau. L’objectif n’est pas la migration intégrale immédiate mais la récupération de 80 % du gain en 4 semaines avec 20 % de l’effort. Le reste se fait sur 2-3 mois sans pression.

Tester une API Hono

Hono permet de tester sans démarrer un serveur HTTP : on appelle app.fetch() directement avec une Request construite à la main. Tests rapides, déterministes, parfaits pour la CI.

// tests/clients.test.ts
import { describe, it, expect } from 'vitest';
import { app } from '../src/index';

describe('GET /api/clients', () => {
  it('retourne 401 sans token', async () => {
    const r = await app.fetch(new Request('http://localhost/api/clients'));
    expect(r.status).toBe(401);
  });
  it('retourne la liste avec un token valide', async () => {
    const r = await app.fetch(new Request('http://localhost/api/clients', {
      headers: { Authorization: 'Bearer ' + validToken }
    }));
    expect(r.status).toBe(200);
    const data = await r.json();
    expect(Array.isArray(data)).toBe(true);
  });
});

Cette approche teste le comportement réel de l’API (middlewares, routing, validation) sans mocking excessif. Un test unitaire d’un endpoint Hono prend 5 à 15 ms. Une suite de 200 tests couvre l’ensemble en moins de 5 secondes — la CI reste rapide même quand le projet grossit.

Quand ne pas choisir Hono

Trois situations où un autre framework reste préférable. Premièrement, si le projet repose massivement sur l’écosystème de middlewares Express très spécifiques (passport stratégies obscures, middlewares tiers non maintenus, intégrations propriétaires) : la réécriture coûterait plus que le gain de performance. Deuxièmement, pour une API monolithique très spécialisée dans un domaine où Fastify a un avantage écosystème (par exemple JSON Schema strict, intégration native AJV) — Fastify reste un choix solide. Troisièmement, si l’équipe est entièrement junior et n’a jamais déployé de service Node : la documentation Hono assume une certaine maturité, et un framework plus directif comme NestJS peut servir de garde-fou au prix d’une complexité supplémentaire.

Pour les autres cas — startup ouest-africaine qui démarre, agence qui livre des projets clients, équipe interne qui modernise son back-office — Hono est le choix le plus rentable en 2026. La courbe d’apprentissage est courte, la portabilité multi-runtime préserve les options pour le futur, et le coût d’infrastructure baisse mécaniquement par rapport à Express ou NestJS.