oRPC: Ein Typ-sicherer API-Stack, der Verträge über alles stellt

Das Problem: Typen, die auf dem Weg verloren gehen

In klassischen API-Projekten definierst du einen Vertrag, dann implementierst du den Server, und der Client wird oft per Hand geschrieben oder mit generierten Typen versorgt. Diese Trennung führt zu Drift: Der Server ändert ein Feld, der Client weiß es nicht, und erst zur Laufzeit fliegt der Fehler. oRPC adressiert genau dieses Problem, indem es den Vertrag als einzige Quelle der Wahrheit setzt. Die README nennt das Paket @orpc/contract explizit: „Define API contract as the single source of truth.“ Aus diesem Vertrag werden dann Server, Client und OpenAPI-Dokumentation abgeleitet. Das Framework richtet sich an TypeScript-Entwickler, die End-to-End-Typensicherheit wollen, ohne auf separate Codegenerierung angewiesen zu sein. Es ist kein Werkzeug für alle, sondern für Teams, die bereit sind, ihre API-Struktur um einen zentralen Vertrag herum zu organisieren.

So funktioniert der Vertrags-Mechanismus

Der Kern liegt in der Trennung von Vertrag und Implementierung. Du definierst mit @orpc/contract die Form deiner Prozeduren: Eingaben, Ausgaben, Fehler. Der Server (@orpc/server) implementiert diesen Vertrag, der Client (@orpc/client) konsumiert ihn mit vollständiger Typinferenz. Die README beschreibt diesen Fluss als „Build APIs or implement contracts“ auf der Server-Seite und „Consume APIs with end-to-end type safety“ auf der Client-Seite. Die Typen fließen also nicht durch separate Generierung, sondern durch TypeScripts eigene Inferenz, was den Drift reduziert. Ein wichtiger Aspekt ist die Integrationsschicht: @orpc/openapi stellt die Kompatibilität zu OpenAPI her, sodass du bestehende Tools wie Swagger UI anbinden kannst. Der Clou ist, dass die Verträge nicht an ein bestimmtes Schema-Validierungssystem gebunden sind. Du kannst Zod, Valibot oder ArkType verwenden, je nachdem, was dein Team bereits nutzt. Das macht oRPC flexibel, aber auch komplex, weil du dich für einen Validator entscheiden musst, bevor du loslegst.

Installation und erste Schritte: Ein Ökosystem aus Paketen

Die Installation ist nicht ein einzelnes npm-Paket, sondern eine Auswahl. Für den Einstieg brauchst du mindestens @orpc/contract, @orpc/server und @orpc/client. Dazu kommt ein Schema-Validator, zum Beispiel @orpc/zod. Die README listet alle Pakete auf, aber es gibt kein Beispiel für einen konkreten Befehl. Du musst also selbst herausfinden, wie die Pakete zusammenspielen. Die Dokumentation auf orpc.dev verspricht hier Abhilfe, aber aus dem Repository selbst geht nicht hervor, wie ein minimales Setup aussieht. Das ist eine Hürde für Neulinge. Ein möglicher Ansatz ist, mit dem Vertrag zu beginnen: Du definierst eine Prozedur, implementierst sie im Server und erstellst einen Client. Die Pakete für Next.js (@orpc/next) oder NestJS (@orpc/nest) zeigen, dass das Framework in bestehende Frameworks integriert werden kann, aber sie setzen voraus, dass du das Grundkonzept verstanden hast. Die Beta-Versionen (v2.0.0-beta.31) deuten darauf hin, dass sich die API noch ändern kann, also solltest du die Versionshinweise im Auge behalten.

Die Stärke: Schema-Koerzion und Edge-Features

Ein besonderes Merkmal ist das Paket @orpc/json-schema, das „Smart coercion for OpenAPI requests“ verspricht. OpenAPI-Requests kommen oft mit Strings an, auch wenn das Schema einen Integer oder Boolean erwartet. Die Koerzion wandelt diese Werte automatisch um. Das ist praktisch, aber auch gefährlich, wenn du strenge Validierung erwartest. Die README nennt es „smart“, was darauf hindeutet, dass die Umwandlung kontextabhängig ist, aber die Details fehlen. Dazu kommen Edge-spezifische Pakete: @orpc/hibernation nutzt Cloudflares Hibernation WebSocket API, @orpc/cloudflare bietet Adapter für RateLimit und Durable Objects. Das zeigt, dass oRPC nicht nur für klassische Server gedacht ist, sondern explizit für die Edge-Laufzeit. Für Entwickler, die auf Cloudflare Workers setzen, ist das ein klarer Vorteil gegenüber generischen API-Frameworks, die diese Integrationen selbst bauen müssen.

Grenzen und Fehlerquellen: Wo oRPC scheitert

Die größte Einschränkung ist der Beta-Status. Version 2.0.0-beta.31 wurde Ende August 2026 veröffentlicht, was bedeutet, dass die API noch nicht stabil ist. Breaking Changes sind wahrscheinlich, und die Dokumentation könnte hinterherhinken. Ein weiteres Problem ist die Paketvielfalt: Über 20 Pakete, von @orpc/publisher bis @orpc/experimental-msw. Das führt zu einer Fragmentierung. Du musst wissen, welche Pakete du brauchst, und die Abhängigkeiten können sich gegenseitig beeinflussen. Die README erwähnt keine zentrale Konfigurationsdatei, sondern setzt auf TypeScript-Typen. Das ist mächtig, aber auch fehleranfällig, wenn du komplexe Typen verschachtelst. Außerdem ist oRPC nicht für Projekte geeignet, die ihre API über mehrere Sprachen hinweg teilen. Die Typensicherheit funktioniert nur innerhalb von TypeScript. Wenn dein Client in Python oder Go geschrieben ist, bringt dir der Vertrag wenig, und du bist wieder auf OpenAPI-Generierung angewiesen.

Alternativen: tRPC und OpenAPI-Generatoren

Der offensichtlichste Vergleich ist tRPC, das ebenfalls Typesafe APIs in TypeScript bietet. Der Unterschied liegt im Ansatz: tRPC ist in erster Linie für Client-Server-Kommunikation innerhalb eines TypeScript-Ökosystems gedacht, oft mit Next.js. oRPC geht einen Schritt weiter, indem es Verträge als separate Einheit definiert und OpenAPI-Kompatibilität als Feature anbietet. tRPC hat keine eingebaute OpenAPI-Unterstützung, du musst zusätzliche Tools wie trpc-openapi verwenden. oRPC hat dafür die Pakete @orpc/openapi und @orpc/json-schema. Ein anderer Ansatz sind klassische OpenAPI-Generatoren wie openapi-typescript oder swagger-codegen. Diese erzeugen Typen aus einer OpenAPI-Spezifikation, aber sie sind nicht bidirektional. Du musst die Spezifikation manuell pflegen, und die Typen können von der Implementierung abweichen. oRPC dreht die Richtung um: Der Vertrag ist der Code, und OpenAPI wird daraus abgeleitet. Das ist ein fundamentaler Unterschied, der für Teams, die mit OpenAPI-Dokumenten arbeiten müssen, entweder ein Segen oder ein Hindernis ist.

Wartung, Lizenz und Upgrade-Kosten

Die Lizenz ist MIT, was für kommerzielle Projekte unproblematisch ist. Du kannst den Code frei nutzen, modifizieren und verteilen. Die Wartung hängt von der Aktivität des Projekts ab. Die letzten Pushs und Releases zeigen eine hohe Frequenz: Drei Beta-Versionen innerhalb weniger Tage. Das bedeutet, dass das Projekt aktiv entwickelt wird, aber auch, dass du bei jedem Update mit Änderungen rechnen musst. Die Upgrade-Kosten sind nicht dokumentiert. Es gibt keine Migrationsanleitung im README, und die Versionsnummern mit Beta-Suffix deuten darauf hin, dass du dich auf Breaking Changes einstellen musst. Ein Trost ist die Modularität: Wenn du nur @orpc/contract und @orpc/server verwendest, ist das Upgrade-Risiko geringer als bei einem Monolithen. Aber die Integration mit @orpc/next oder @orpc/nest könnte bei Framework-Updates zusätzliche Arbeit bedeuten. Bevor du oRPC in Produktion einsetzt, solltest du die Changelogs der einzelnen Pakete prüfen und testen, ob deine Verträge nach einem Update noch typkorrekt sind.

Redaktionelles Fazit

oRPC richtet sich an TypeScript-Teams, die eine vertragsbasierte API-Entwicklung mit strikter Typensicherheit über den gesamten Stack suchen und bereit sind, sich in ein junges Ökosystem einzuarbeiten. Wer stabile Produktionsreleases, minimale Abhängigkeiten oder eine enge Integration in ein bestehendes Framework wie tRPC ohne Zusatzschicht benötigt, sollte noch warten. Vor der Adoption solltest du die Dokumentation auf orpc.dev prüfen, ob die Beta-Status der Pakete deinen Anforderungen entspricht, und testen, ob die Schema-Validatoren (Zod, Valibot, ArkType) mit deinen bestehenden Schemas kompatibel sind. Die Vertragsdefinition mit @orpc/contract ist der zentrale Einstiegspunkt, und du solltest klären, ob die zusätzlichen Pakete wie @orpc/publisher oder @orpc/hibernation für deinen Einsatz wirklich notwendig sind oder ob du sie weglassen kannst.

Offizielle Quellen

1. Official documentation
2. Official README
3. Project repository
4. Release notes