TypeScript mit Hono: Schlankes Edge-Ready Backend Framework

1. Was Hono anders macht: Web-Standards statt Node-APIs

Die meisten etablierten Node-Frameworks bauen auf den nativen HTTP-Typen von Node.js auf, was sie an die Node-Runtime bindet. Hono geht einen anderen Weg: Es nutzt konsequent die Web-Standard-APIs Request und Response, wie sie in Browsern und modernen Runtimes wie Cloudflare Workers, Deno und Bun ohnehin bereits vorhanden sind. Das Ergebnis ist ein TypeScript-Framework, das ohne Anpassung auf mehreren Runtimes gleichzeitig laeuft, statt eine davon zu bevorzugen.

Fuer Teams, die TypeScript mit Hono einsetzen, bedeutet das konkret: derselbe Code, der lokal unter Node.js entwickelt wurde, laesst sich unveraendert auf einer Edge-Plattform ausrollen, wo Anfragen naeher am Endnutzer verarbeitet werden. Diese Portabilitaet ist kein Nebeneffekt, sondern das zentrale Designziel von Hono, und sie zeigt sich durchgaengig in der API-Gestaltung des Frameworks.

Trotz seiner geringen Groesse verzichtet Hono nicht auf typsicheres Routing, Middleware-Verkettung und Validierung. Dieser Artikel zeigt, wie diese Bausteine zusammenspielen, mit besonderem Fokus auf den RPC-Modus, der bei anderen Frameworks in dieser Form nicht existiert.

2. Installation und Grundgeruest

Ein minimales Hono-Projekt kommt mit einer einzigen Abhaengigkeit aus, dem Kernpaket hono selbst. Fuer den Zieleinsatz auf Cloudflare Workers oder Bun wird kein zusaetzliches Framework-Overhead benoetigt, was Kaltstartzeiten in Edge-Umgebungen spuerbar reduziert. Die grundlegende Struktur einer Anwendung besteht aus einer Hono-Instanz, auf der Routen mit HTTP-Methoden wie get, post und put registriert werden, aehnlich wie bei Express, aber mit durchgehend typisierten Rueckgabewerten.

Ein zentraler Unterschied zu Node-basierten Frameworks: Der Export am Ende der Datei ist bei Hono selbst die Anwendung, nicht ein separater Server-Start-Aufruf. Je nach Zielplattform uebernimmt die Runtime selbst das Starten, etwa ueber export default app bei Cloudflare Workers oder ueber ein kleines Adapter-Paket bei Node.js.

// index.ts — minimal Hono application, runtime agnostic
import { Hono } from "hono";

type Bindings = {
  DATABASE_URL: string;
};

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

app.get("/", (c) => {
  return c.text("Hono is running");
});

app.get("/health", (c) => {
  return c.json({ status: "ok", runtime: "edge-or-node" });
});

// Same export works for Cloudflare Workers, Deno, Bun and, with
// an adapter, Node.js
export default app;

3. Das Kontext-Objekt c und typsichere Handler

Statt separater req- und res-Parameter wie bei Express nutzt Hono ein einzelnes Kontext-Objekt, ueblicherweise c genannt. Dieses Objekt buendelt Zugriff auf den Request, Hilfsmethoden zum Erzeugen der Antwort wie c.json() und c.text(), sowie einen typisierten Variablen-Speicher fuer Werte, die Middleware an nachfolgende Handler weitergibt.

Der generische Typ-Parameter von Hono erlaubt es, sowohl Umgebungsvariablen (Bindings) als auch Middleware-Variablen (Variables) fest zu deklarieren. Damit kennt TypeScript bei jedem Zugriff auf c.env oder c.get() den korrekten Typ, ohne dass an jeder Verwendungsstelle eine manuelle Typ-Annotation noetig waere. Das ist ein deutlicher Unterschied zu Express, wo aehnliche Erweiterungen ueber globale Modul-Augmentation gehen und weniger granular typisiert sind.

4. Routing und typsichere Path-Parameter

Path-Parameter werden in Hono mit dem Doppelpunkt-Syntax deklariert, etwa /users/:id, und ueber c.req.param("id") ausgelesen. TypeScript leitet den erwarteten Parameter-Namen direkt aus dem Pfad-String ab: Tippt man beim Auslesen einen Namen, der im Pfad nicht existiert, meldet der Compiler sofort einen Fehler, ganz ohne manuell definiertes Interface fuer die Parameter, wie es bei Express noetig waere.

Diese Typableitung aus dem Pfad-String selbst ist eines der praktischsten Features von Hono fuer TypeScript-Entwickler: Route und Parameter-Typ bleiben immer synchron, weil beide aus derselben Quelle, dem Pfad-String, stammen. Aenderungen am Pfad, etwa das Umbenennen eines Parameters, schlagen sich sofort im Compiler nieder, statt erst zur Laufzeit als undefined aufzufallen.

// routes/users.ts — path parameter type is inferred from the route string
import { Hono } from "hono";

const users = new Hono();

users.get("/:id", (c) => {
  // TypeScript knows "id" exists because it appears in "/:id"
  const id = c.req.param("id");
  return c.json({ id, name: "Example User" });
});

users.get("/:id/orders/:orderId", (c) => {
  // Both parameters are inferred, typo-safe against the path string
  const { id, orderId } = c.req.param();
  return c.json({ userId: id, orderId });
});

export default users;

5. Middleware-System und Typen-Vererbung

Middleware in Hono wird mit app.use() registriert und erhaelt Zugriff auf denselben Kontext wie ein normaler Handler. Eine Middleware kann ueber c.set() einen Wert im typisierten Variablen-Speicher hinterlegen, den nachfolgende Handler ueber c.get() typsicher auslesen, solange der Variables-Typ der Hono-Instanz entsprechend deklariert wurde. Das ersetzt das in Express uebliche, aber weniger typsichere Anhaengen zusaetzlicher Felder am Request-Objekt.

Ein haeufiges Muster ist eine Auth-Middleware, die einen validierten Benutzer im Kontext ablegt, sodass spaetere Handler direkt und typsicher darauf zugreifen koennen, ohne den Benutzer erneut zu laden oder zu pruefen. Middleware laesst sich in Hono auch pro Route statt global registrieren, was fein granulare Kontrolle darueber erlaubt, welche Routen welche Middleware durchlaufen.

// auth-middleware.ts — typed variables shared with downstream handlers
import { createMiddleware } from "hono/factory";

type AuthVariables = {
  userId: string;
  role: "admin" | "editor" | "viewer";
};

export const requireAuth = createMiddleware<{ Variables: AuthVariables }>(
  async (c, next) => {
    const token = c.req.header("Authorization");
    if (!token) {
      return c.json({ error: "Missing token" }, 401);
    }
    // In production, verify the token against an identity provider
    c.set("userId", "u_123");
    c.set("role", "editor");
    await next();
  }
);

// routes/profile.ts
app.get("/profile", requireAuth, (c) => {
  // c.get("userId") is typed as string, not any
  return c.json({ userId: c.get("userId"), role: c.get("role") });
});

6. Validierung mit dem Zod-Validator

Das offizielle Paket @hono/zod-validator bringt Zod-Validierung als Middleware in Hono ein und legt das validierte, korrekt typisierte Ergebnis ueber c.req.valid() ab. Dieses Pattern gleicht konzeptionell der Zod-Middleware aus dem Express-Artikel, ist bei Hono aber enger in den Kontext integriert, weil c.req.valid("json") direkt den aus dem Schema abgeleiteten Typ zurueckgibt, ohne einen zusaetzlichen Type Cast im Handler.

Wichtig fuer TypeScript-Projekte: Der Validator unterstuetzt getrennte Ziele fuer json, query, param und header, was mehrfache Validierung derselben Route ohne Ueberschneidungen ermoeglicht. Fehlgeschlagene Validierung fuehrt standardmaessig zu einer 400-Antwort, das Verhalten laesst sich aber ueber einen dritten Middleware-Parameter individuell anpassen.

7. RPC-Modus: Client-Typen automatisch ableiten

Das auffaelligste Feature von Hono im Vergleich zu Express und Fastify ist der RPC-Modus: Mit hc, dem Hono-Client, laesst sich aus dem Typ der Server-Anwendung direkt ein typsicherer HTTP-Client erzeugen, ganz ohne separate Codegenerierung, ohne OpenAPI-Zwischenschritt und ohne manuell gepflegte Client-SDKs. Voraussetzung dafuer ist, dass Routen mit method chaining registriert werden, damit TypeScript den vollstaendigen Routen-Typ inferieren kann.

In der Praxis bedeutet das: Aendert ein Backend-Entwickler eine Route, etwa indem ein Feld im Response-Objekt entfernt wird, meldet der Compiler auf der Client-Seite sofort einen Typfehler, sobald das entfernte Feld dort noch verwendet wird. Diese enge Kopplung erinnert konzeptionell an tRPC, ist bei Hono aber direkt im Framework integriert, statt eine separate Bibliothek zu erfordern.

// server.ts — chained routes so the type can be inferred by the client
import { Hono } from "hono";

const app = new Hono()
  .get("/posts/:id", (c) => {
    const id = c.req.param("id");
    return c.json({ id, title: "Example Post" });
  })
  .post("/posts", async (c) => {
    const body = await c.req.json<{ title: string }>();
    return c.json({ id: "p_1", title: body.title }, 201);
  });

export type AppType = typeof app;
export default app;

// client.ts — no code generation, type comes straight from the server
import { hc } from "hono/client";
import type { AppType } from "./server";

const client = hc<AppType>("https://api.example.com");

const res = await client.posts[":id"].$get({ param: { id: "p_1" } });
const post = await res.json(); // fully typed as { id: string; title: string }

8. Deployment auf Cloudflare Workers, Deno und Bun

Weil Hono ausschliesslich Web-Standard-APIs verwendet, ist derselbe Anwendungscode auf mehreren Runtimes lauffaehig, ohne Framework-spezifische Anpassungen. Auf Cloudflare Workers wird die exportierte Hono-Instanz direkt als Worker-Handler verwendet, Bindings wie Datenbankverbindungen oder KV-Namespaces werden ueber den generischen Bindings-Typ typsicher an c.env angebunden. Deno und Bun benoetigen jeweils nur einen kleinen Serve-Aufruf, der die Hono-Instanz an die native Server-API der jeweiligen Runtime weiterreicht.

Fuer klassisches Node.js gibt es das Adapter-Paket @hono/node-server, das die Web-Standard-Objekte von Hono auf die Node-HTTP-API abbildet. Dieses Muster erlaubt es Teams, denselben TypeScript-Code lokal unter Node.js zu entwickeln und zu testen, bevor er unveraendert auf einer Edge-Plattform mit geografisch verteilten Instanzen ausgerollt wird.

9. Hono im Vergleich zu Express und Fastify

Waehrend Express und Fastify fest an Node.js gebunden sind, spielt Hono seine Staerke besonders dort aus, wo Anwendungen auf mehreren Runtimes oder direkt an der Edge laufen sollen. Fuer klassische, langlebige Node-Server bleiben Express und Fastify oft die pragmatischere Wahl, allein wegen des groesseren Oekosystems an Middleware und Integrationen. TypeScript mit Hono lohnt sich besonders dann, wenn ein Projekt von Anfang an auf Portabilitaet zwischen Runtimes oder auf den RPC-Modus fuer typsichere Frontend-Backend-Kommunikation setzt.

Ein weiterer Faktor ist die Teamgroesse des Oekosystems: Hono ist juenger als Express und Fastify, wodurch manche Nischen-Middleware noch fehlt, die es fuer die etablierten Frameworks bereits gibt. Fuer Standard-CRUD-APIs mit Fokus auf Edge-Deployment und Typsicherheit ist dieser Nachteil in der Praxis meist gering, weil die wichtigsten Bausteine wie Validierung, CORS und JWT-Handling bereits als offizielle Hono-Middleware existieren.

10. Zusammenfassung

TypeScript mit Hono zeigt, wie ein Backend-Framework aussieht, das konsequent auf Web-Standard-APIs statt Node-spezifischer Typen setzt. Path-Parameter werden direkt aus dem Route-String inferiert, das Kontext-Objekt buendelt Request, Response und typisierten Variablen-Speicher, und Middleware reicht Werte typsicher an nachfolgende Handler weiter. Der RPC-Modus ist das Alleinstellungsmerkmal von Hono: ein typsicherer Client entsteht direkt aus dem Server-Typ, ganz ohne Codegenerierung oder separates Schema.

Fuer Teams, die Portabilitaet zwischen Node.js, Cloudflare Workers, Deno und Bun brauchen, oder die typsichere Frontend-Backend-Kommunikation ohne zusaetzliches Tooling wollen, ist Hono eine der konsequentesten Optionen im TypeScript-Oekosystem. Fuer etablierte Node-only-Projekte mit grossem Bestand an Express-Middleware bleibt die Migration meist eine Abwaegung zwischen dem Gewinn an Typsicherheit und dem Aufwand der Umstellung.

11. FAQ: TypeScript mit Hono