Comment créer une API REST open source avec Hono et Bun en 7 étapes

Express a dominé le développement d'API REST en JavaScript pendant plus de 15 ans. Mais en 2026, le paysage a changé. Bun remplace progressivement Node.js comme runtime de référence, et Hono — un framework web ultralight de 14 Ko, TypeScript-first, compatible avec tous les runtimes modernes — est devenu l'alternative la plus populaire à Express. Ce guide vous montre comment créer une API REST complète, testée et prête pour la production en 7 étapes pratiques. Chaque étape inclut du code que vous pouvez copier, exécuter et modifier.

Étape 1 : Installer Bun et initialiser le projet

Bun est un runtime JavaScript/TypeScript tout-en-un : moteur d'exécution, bundler, test runner et gestionnaire de packages. Il est écrit en Zig et utilise JavaScriptCore (le moteur de Safari) au lieu de V8 (Chrome/Node.js), ce qui lui confère des performances supérieures en démarrage à froid et en I/O.

Commencez par installer Bun si ce n'est pas déjà fait :

# Installer Bun (Linux, macOS, WSL)
curl -fsSL https://bun.sh/install | bash

# Verifier l'installation
bun --version  # 2.x

# Initialiser le projet
mkdir mon-api-hono && cd mon-api-hono
bun init -y

# Installer Hono
bun add hono

# Installer les dependances de dev
bun add -d @types/bun

La structure initiale du projet est minimaliste. Bun génère un package.json, un tsconfig.json et un fichier index.ts. Le TypeScript fonctionne nativement — pas besoin de ts-node ou de compilation séparée.

Étape 2 : Créer votre première route avec Hono

Hono utilise une API familière pour les développeurs Express, mais avec des différences fondamentales : il est basé sur les Web Standards (Request / Response), il est typé de bout en bout avec TypeScript, et son routeur utilise un trie compressé pour un matching O(1).

// src/index.ts
import { Hono } from "hono";

const app = new Hono();

// Route de sante
app.get("/health", (c) => {
  return c.json({ status: "ok", timestamp: new Date().toISOString() });
});

// Route d'accueil
app.get("/", (c) => {
  return c.json({
    name: "Mon API Hono",
    version: "1.0.0",
    docs: "/docs",
  });
});

// Demarrer le serveur
export default {
  port: Number(process.env.PORT) || 3000,
  fetch: app.fetch,
};

Lancez le serveur avec bun run src/index.ts. C'est tout. Pas de configuration, pas de compilation. Le serveur démarre en moins de 10 millisecondes. Testez avec curl http://localhost:3000/health.

Remarquez la syntaxe export default : c'est le pattern Bun pour démarrer un serveur HTTP. Le runtime détecte l'export et lance automatiquement le serveur. Pas besoin d'appeler app.listen() comme avec Express.

Étape 3 : Structurer le projet en couches

Pour une API maintenable, structurez le code en couches séparées : routes (définition des endpoints), handlers (logique de traitement), services (logique métier), schemas (validation). Voici la structure recommandée :

mon-api-hono/
├── src/
│   ├── index.ts           # Point d'entree
│   ├── routes/
│   │   ├── users.ts       # Routes /users
│   │   └── posts.ts       # Routes /posts
│   ├── handlers/
│   │   ├── users.ts       # Handlers utilisateurs
│   │   └── posts.ts       # Handlers articles
│   ├── schemas/
│   │   ├── user.ts        # Schemas Zod utilisateur
│   │   └── post.ts        # Schemas Zod article
│   ├── services/
│   │   └── database.ts    # Couche donnees
│   └── middleware/
│       ├── auth.ts        # Authentification
│       └── logger.ts      # Logging
├── tests/
│   └── api.test.ts        # Tests d'integration
├── Dockerfile
├── docker-compose.yml
├── package.json
└── tsconfig.json

Créons le fichier de routes utilisateurs avec validation Zod — la bibliothèque de validation TypeScript-first qui est devenue le standard en 2026.

// src/schemas/user.ts
import { z } from "zod";

export const createUserSchema = z.object({
  name: z.string().min(2).max(100),
  email: z.string().email(),
  role: z.enum(["admin", "user", "moderator"]).default("user"),
});

export const updateUserSchema = createUserSchema.partial();

export type CreateUser = z.infer<typeof createUserSchema>;
export type UpdateUser = z.infer<typeof updateUserSchema>;

// src/routes/users.ts
import { Hono } from "hono";
import { zValidator } from "@hono/zod-validator";
import { createUserSchema, updateUserSchema } from "../schemas/user";

const users = new Hono();

// Simuler une base de donnees en memoire
let db: Array<{ id: string; name: string; email: string; role: string }> = [];

// GET /users — Liste tous les utilisateurs
users.get("/", (c) => {
  const page = Number(c.req.query("page") || 1);
  const limit = Number(c.req.query("limit") || 10);
  const start = (page - 1) * limit;

  return c.json({
    data: db.slice(start, start + limit),
    total: db.length,
    page,
    limit,
  });
});

// GET /users/:id — Un utilisateur par ID
users.get("/:id", (c) => {
  const user = db.find((u) => u.id === c.req.param("id"));
  if (!user) return c.json({ error: "Utilisateur non trouve" }, 404);
  return c.json(user);
});

// POST /users — Creer un utilisateur
users.post("/", zValidator("json", createUserSchema), (c) => {
  const body = c.req.valid("json");
  const user = { id: crypto.randomUUID(), ...body };
  db.push(user);
  return c.json(user, 201);
});

// PATCH /users/:id — Modifier un utilisateur
users.patch("/:id", zValidator("json", updateUserSchema), (c) => {
  const idx = db.findIndex((u) => u.id === c.req.param("id"));
  if (idx === -1) return c.json({ error: "Utilisateur non trouve" }, 404);
  db[idx] = { ...db[idx], ...c.req.valid("json") };
  return c.json(db[idx]);
});

// DELETE /users/:id — Supprimer un utilisateur
users.delete("/:id", (c) => {
  const idx = db.findIndex((u) => u.id === c.req.param("id"));
  if (idx === -1) return c.json({ error: "Utilisateur non trouve" }, 404);
  db.splice(idx, 1);
  return c.json({ deleted: true });
});

export default users;

Notez l'utilisation de zValidator : Hono valide automatiquement le corps de la requête contre le schéma Zod. Si la validation échoue, une réponse 400 avec les détails des erreurs est renvoyée avant que votre handler ne soit appelé. C'est du code qu'Express vous forcerait à écrire manuellement.

Étape 4 : Ajouter les middleware essentiels

Hono inclut des middleware intégrés qui couvrent 90 % des besoins d'une API REST. Voici les indispensables.

// src/index.ts — version complete avec middleware
import { Hono } from "hono";
import { cors } from "hono/cors";
import { logger } from "hono/logger";
import { secureHeaders } from "hono/secure-headers";
import { rateLimiter } from "hono/rate-limiter";
import { prettyJSON } from "hono/pretty-json";
import users from "./routes/users";

const app = new Hono();

// Middleware globaux
app.use("*", logger());             // Log chaque requete
app.use("*", secureHeaders());       // Headers de securite (CSP, HSTS...)
app.use("*", prettyJSON());          // JSON formate en dev
app.use("*", cors({
  origin: ["https://monsite.fr", "http://localhost:3001"],
  allowMethods: ["GET", "POST", "PATCH", "DELETE"],
  allowHeaders: ["Content-Type", "Authorization"],
}));

// Rate limiting — 100 requetes par minute par IP
app.use("*", rateLimiter({
  windowMs: 60 * 1000,
  limit: 100,
  keyGenerator: (c) => c.req.header("x-forwarded-for") || "unknown",
}));

// Monter les routes
app.route("/users", users);

// Route de sante
app.get("/health", (c) =>
  c.json({ status: "ok", uptime: process.uptime() })
);

// Gestion d'erreurs globale
app.onError((err, c) => {
  console.error(err);
  return c.json(
    { error: "Erreur interne", message: err.message },
    500
  );
});

// 404 handler
app.notFound((c) =>
  c.json({ error: "Route non trouvee", path: c.req.path }, 404)
);

export default {
  port: Number(process.env.PORT) || 3000,
  fetch: app.fetch,
};

Avec Express, chacun de ces middleware nécessiterait un package npm séparé (helmet, cors, morgan, express-rate-limit). Avec Hono, tout est intégré — zéro dépendance supplémentaire, zéro risque de supply chain attack.

Étape 5 : Écrire les tests avec le test runner de Bun

Bun inclut un test runner natif compatible avec la syntaxe Jest/Vitest. Pas besoin d'installer jest, vitest, supertest ou ts-jest. Le testing est intégré au runtime.

// tests/api.test.ts
import { describe, it, expect } from "bun:test";
import app from "../src/index";

const baseUrl = "http://localhost:3000";

describe("API Users", () => {
  it("GET /health retourne status ok", async () => {
    const res = await app.fetch(
      new Request(`${baseUrl}/health`)
    );
    expect(res.status).toBe(200);
    const body = await res.json();
    expect(body.status).toBe("ok");
  });

  it("POST /users cree un utilisateur", async () => {
    const res = await app.fetch(
      new Request(`${baseUrl}/users`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          name: "Jean Dupont",
          email: "jean@example.fr",
          role: "user",
        }),
      })
    );
    expect(res.status).toBe(201);
    const user = await res.json();
    expect(user.name).toBe("Jean Dupont");
    expect(user.id).toBeDefined();
  });

  it("POST /users refuse un email invalide", async () => {
    const res = await app.fetch(
      new Request(`${baseUrl}/users`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          name: "Test",
          email: "pas-un-email",
        }),
      })
    );
    expect(res.status).toBe(400);
  });

  it("GET /users retourne la liste paginee", async () => {
    const res = await app.fetch(
      new Request(`${baseUrl}/users?page=1&limit=5`)
    );
    expect(res.status).toBe(200);
    const body = await res.json();
    expect(body.data).toBeInstanceOf(Array);
    expect(body.page).toBe(1);
  });
});

Lancez les tests avec bun test. Pas de configuration, pas de fichier jest.config.ts. Les tests s'exécutent en quelques millisecondes grâce au démarrage instantané de Bun. La fonction app.fetch permet de tester l'API sans démarrer de serveur HTTP — les requêtes sont traitées directement en mémoire.

Étape 6 : Containeriser avec Docker pour la production

Pour un déploiement reproductible, containerisez votre API avec Docker. Bun fournit des images officielles optimisées.

# Dockerfile
FROM oven/bun:2 AS base
WORKDIR /app

# Installer les dependances
FROM base AS deps
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile --production

# Build
FROM base AS build
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile
COPY src/ src/
COPY tsconfig.json ./

# Production
FROM base AS production
COPY --from=deps /app/node_modules node_modules
COPY --from=build /app/src src
COPY --from=build /app/package.json .

# Utilisateur non-root
USER bun

EXPOSE 3000
ENV NODE_ENV=production
CMD ["bun", "run", "src/index.ts"]

# docker-compose.yml
services:
  api:
    build: .
    ports:
      - "3000:3000"
    environment:
      - PORT=3000
      - NODE_ENV=production
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 5s
      retries: 3

L'image Docker multi-stage produit un conteneur de moins de 100 Mo, contre 300 à 500 Mo pour une image Node.js équivalente. Le démarrage à froid est inférieur à 50 ms. Pour un hébergement souverain français, déployez sur Scaleway (Containers), Clever Cloud, ou OVHcloud (Managed Kubernetes). Consultez notre guide sur le déploiement Docker sécurisé pour les bonnes pratiques complètes.

Étape 7 : Publier en open source et documenter

La dernière étape transforme votre API en projet open source contribuable. Ajoutez les fichiers essentiels :

# Fichiers a ajouter
LICENSE            # MIT ou Apache 2.0 recommande
README.md          # Installation, usage, API reference
CONTRIBUTING.md    # Comment contribuer
.github/
  workflows/
    ci.yml         # GitHub Actions : lint + test + build

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - run: bun install --frozen-lockfile
      - run: bun test
      - run: bun build src/index.ts --outdir dist

Pour la documentation d'API, Hono supporte la génération OpenAPI 3.1 automatique via le package @hono/zod-openapi. Vos schémas Zod deviennent la source de vérité pour la validation et la documentation. Installez également @hono/swagger-ui pour servir une interface Swagger directement depuis votre API — accessible à /docs.

Publiez sur GitHub avec une licence MIT (pour maximiser l'adoption) ou Apache 2.0 (pour la protection des brevets). Ajoutez des topics GitHub (hono, bun, api-rest, typescript, open-source) pour améliorer la découvrabilité. Pour un guide complet sur la publication open source, consultez notre article sur comment publier un package npm open source.

Benchmarks : Hono + Bun vs. Express + Node.js

Les performances sont le principal argument de Hono + Bun face à Express + Node.js. Voici des benchmarks mesurés sur une machine Linux avec 4 vCPU, 8 Go RAM, en utilisant wrk sur un endpoint JSON simple :

Ces chiffres ont des implications concrètes. Pour une PME française qui héberge son API chez OVHcloud ou Scaleway, la même charge de travail nécessite 3 à 4 fois moins de serveurs avec Hono + Bun. C'est une réduction directe de la facture cloud. Pour en savoir plus sur la migration depuis Node.js, consultez notre guide sur comment migrer vers Bun 2 en production.

Questions fréquentes