io-ts vs. Zod vs. Valibot: Laufzeit-Validierung im Vergleich

1. Drei Bibliotheken, drei Philosophien der Laufzeit-Validierung

Alle drei Bibliotheken lösen dasselbe Grundproblem: TypeScript-Typen existieren nur zur Kompilierzeit, weshalb externe Daten aus Formularen, APIs oder Konfigurationsdateien eine echte Laufzeit-Prüfung brauchen, bevor ihnen vertraut werden darf. io-ts, Zod und Valibot unterscheiden sich aber fundamental darin, wie diese Prüfung modelliert wird, funktional mit expliziten Either-Werten, objektorientiert mit einer verketteten Fluent-API, oder modular mit einzeln importierbaren Funktionen.

Diese Unterscheidung ist keine reine Geschmacksfrage. Ein Team, das bereits mit fp-ts arbeitet, profitiert von io-ts' konsistenter funktionaler Integration. Ein Team ohne funktionalen Hintergrund findet in Zods Fluent API oft den direkteren Einstieg. Und ein Projekt mit strengen Bundle-Größen-Vorgaben, etwa eine performance-kritische Storefront, gewinnt am meisten von Valibots konsequentem Tree-Shaking. Die folgenden Abschnitte ordnen diese drei Philosophien anhand konkreter Codebeispiele ein.

2. io-ts: Funktionale Validierung im fp-ts-Ökosystem

io-ts war eine der ersten TypeScript-Bibliotheken, die Laufzeit-Validierung und Typinferenz aus einer einzigen Quelle koppelte, lange bevor Zod dieses Konzept populär machte. Der entscheidende Unterschied zu den beiden anderen Bibliotheken liegt im Rückgabewert: io-ts' decode()-Funktion liefert kein Ergebnisobjekt mit einem success-Flag, sondern ein Either-Typ aus dem fp-ts-Ökosystem, das entweder einen Left mit Validierungsfehlern oder einen Right mit dem geprüften Wert enthält.

Diese Kopplung an fp-ts ist zugleich Stärke und Einstiegshürde. Wer bereits mit pipe(), fold() und funktionaler Fehlerbehandlung arbeitet, fügt sich io-ts nahtlos in bestehende Patterns ein. Ohne fp-ts-Erfahrung im Team wirkt der Umgang mit Either gegenüber einem einfachen if (!result.success) zunächst ungewohnt, was io-ts in der Praxis eher zur Wahl von Teams macht, die funktionale Programmierung bereits als Architekturprinzip etabliert haben.

import * as t from "io-ts";
import { pipe } from "fp-ts/function";
import { fold } from "fp-ts/Either";

// io-ts codec: runtime check and static type from one definition
const UserCodec = t.type({
  id: t.string,
  email: t.string,
  age: t.number,
});

type User = t.TypeOf<typeof UserCodec>;

function decodeUser(input: unknown): void {
  // decode() returns an Either<Errors, User>, not a plain result object
  const result = UserCodec.decode(input);

  pipe(
    result,
    fold(
      (errors) => console.error(`Invalid user: ${errors.length} issues`),
      (user: User) => console.log(`Valid user: ${user.email}`)
    )
  );
}

3. Zod: Fluent API und breites Ökosystem

Zod setzt auf eine verkettete, objektorientierte API, die ohne zusätzliche funktionale Bibliothek auskommt. Methoden wie .min(), .email() oder .optional() werden direkt an ein Basis-Schema gehängt, und .safeParse() liefert ein einfaches Ergebnisobjekt mit success-Flag zurück, ein Muster, das für die meisten TypeScript-Entwickler ohne funktionalen Hintergrund sofort verständlich ist.

Der entscheidende Vorteil von Zod liegt im Ökosystem: React Hook Form, tRPC, tanStack Form und zahlreiche weitere Bibliotheken bieten native Zod-Integrationen an, wodurch Zod-Schemas oft nicht nur die Validierung, sondern auch die Typinferenz für ganze Formular- oder RPC-Schichten übernehmen. Diese breite Verbreitung macht Zod häufig zur Standardwahl für neue Projekte, unabhängig davon, ob io-ts oder Valibot technisch überlegen wären.

import { z } from "zod";

// Zod: fluent, chainable API, no separate functional library required
const userSchema = z.object({
  id: z.string(),
  email: z.string().email(),
  age: z.number().int().positive(),
});

type User = z.infer<typeof userSchema>;

function decodeUser(input: unknown): void {
  // safeParse returns a plain result object with a "success" flag
  const result = userSchema.safeParse(input);

  if (!result.success) {
    console.error(`Invalid user: ${result.error.issues.length} issues`);
    return;
  }

  console.log(`Valid user: ${result.data.email}`);
}

4. Valibot: Modulare Funktionen und Tree-Shaking

Valibot ist die jüngste der drei Bibliotheken und wurde gezielt als Antwort auf Zods Bundle-Größen-Problem entworfen. Statt einer zentralen z-Klasse mit gekoppelten Methoden importiert Valibot jede Validierungsfunktion einzeln, string(), email(), minLength(), verbunden über eine funktionale pipe()-Syntax. Ein Bundler entfernt dadurch konsequent jeden Validator, der im Projekt tatsächlich nicht verwendet wird.

Diese Architekturentscheidung macht Valibot zur bevorzugten Wahl für performance-kritische Frontends mit striktem JavaScript-Budget, etwa in einem Hyvä-Kontext. Der Kompromiss: Das Ökosystem an Drittanbieter-Integrationen ist jünger und kleiner als bei Zod, und Teams müssen bei fehlenden Integrationen häufiger selbst nacharbeiten, ein Aufwand, der sich gegen die eingesparte Bundle-Größe abwägen lässt.

import * as v from "valibot";

// Valibot: individual, tree-shakeable functions via a functional pipe
const UserSchema = v.object({
  id: v.string(),
  email: v.pipe(v.string(), v.email()),
  age: v.pipe(v.number(), v.integer(), v.minValue(1)),
});

type User = v.InferOutput<typeof UserSchema>;

function decodeUser(input: unknown): void {
  // safeParse mirrors Zod's result shape, but only imports used validators
  const result = v.safeParse(UserSchema, input);

  if (!result.success) {
    console.error(`Invalid user: ${result.issues.length} issues`);
    return;
  }

  console.log(`Valid user: ${result.output.email}`);
}

5. Fehlerbehandlung im Vergleich: Either, ZodError und Issues

Die Fehlerobjekte der drei Bibliotheken unterscheiden sich strukturell erheblich. io-ts liefert ein Array von ValidationError-Einträgen innerhalb des Left-Zweigs eines Either, jeweils mit einem context-Pfad, der die Position im verschachtelten Typ beschreibt, aber ohne die aus Zod bekannte, direkt lesbare Fehlermeldung. Diese Rohform muss meist zuerst mit einer Hilfsfunktion wie PathReporter.report() in lesbaren Text überführt werden.

Zods ZodError bietet mit .flatten() und .format() zwei eingebaute Methoden, die Fehler direkt in feldbezogene, UI-taugliche Strukturen umwandeln, ein deutlicher Komfortvorsprung gegenüber io-ts. Valibots issues-Array liegt konzeptionell näher an Zod als an io-ts, mit flachen Objekten pro Fehler, die Pfad und Nachricht enthalten, jedoch ohne eine zu Zods flatten() gleichwertige eingebaute Hilfsfunktion, sodass Teams hier häufiger eine eigene, kleine Mapping-Funktion schreiben.

6. Bundle-Größe und Performance in der Praxis

Für ein typisches Formular-Schema mit einem Dutzend Feldern liegt Zod im minifizierten und komprimierten Zustand meist im Bereich von zehn bis vierzehn Kilobyte, unabhängig davon, wie viele der enthaltenen Methoden tatsächlich genutzt werden, da die Kernklasse als zusammenhängender Block importiert wird. Valibot erreicht für dasselbe Schema häufig nur ein bis drei Kilobyte, weil ausschließlich die tatsächlich verwendeten Validierungsfunktionen ins Bundle gelangen.

io-ts liegt bundle-technisch zwischen beiden, abhängig davon, wie viel des fp-ts-Ökosystems ein Projekt bereits ohnehin lädt. Für ein Projekt, das fp-ts schon für State-Management oder asynchrone Datenflüsse nutzt, entstehen durch io-ts kaum zusätzliche Kosten. Für ein Projekt ohne bestehende fp-ts-Abhängigkeit bringt io-ts das komplette funktionale Fundament als zusätzliche Last mit, was die Bundle-Größe deutlich über Zod und Valibot heben kann.

7. Ökosystem-Integration: Formulare, RPC und Codegen

Zods Marktanteil zeigt sich am deutlichsten in der Zahl der Drittanbieter-Integrationen: React Hook Form, tRPC, tanStack Router und tanStack Form bieten native Zod-Adapter, wodurch ein einziges Schema Formularvalidierung, API-Vertrag und Routenparameter gleichzeitig typisiert. Diese Netzwerkeffekte machen Zod häufig zur pragmatischsten Wahl, selbst wenn Valibot technisch die leichtere Option wäre.

Valibots Ökosystem wächst, seit tanStack Form und einige RPC-Bibliotheken Valibot-Adapter parallel zu ihren Zod-Adaptern anbieten, bleibt aber insgesamt kleiner. io-ts ist am stärksten mit dem fp-ts-Ökosystem selbst verwoben, etwa mit io-ts-types für zusätzliche Codecs, aber kaum mit Formular-Bibliotheken außerhalb des funktionalen Umfelds integriert, was io-ts eher zur internen Validierungsschicht als zum direkten Formular-Bindeglied macht.

8. Migrationsaufwand zwischen den Bibliotheken einschätzen

Eine Migration von Zod zu Valibot betrifft in erster Linie die Syntax, nicht die Struktur: Aus z.object({ email: z.string().email() }) wird v.object({ email: v.pipe(v.string(), v.email()) }), ein mechanischer, oft skriptbarer Umbau, der die Schema-Struktur unverändert lässt. Der abgeleitete Typ wechselt lediglich von z.infer zu v.InferOutput.

Eine Migration zwischen io-ts und Zod oder Valibot ist aufwendiger, weil sie den kompletten Fehlerbehandlungs-Stil verändert, von Either-basiertem Pattern Matching zu einem einfachen if (!result.success). Jede Stelle im Code, die fold() oder pipe() auf ein Validierungsergebnis anwendet, muss umgeschrieben werden, weshalb ein solcher Wechsel meist schrittweise, Modul für Modul, erfolgt statt in einem einzigen großen Refactoring.

9. io-ts, Zod und Valibot im direkten Vergleich

Die folgende Tabelle fasst die wichtigsten Unterschiede zusammen und ordnet jede Bibliothek einem typischen Einsatzszenario zu.

Keine der drei Bibliotheken ist in jeder Kategorie überlegen, die Wahl hängt davon ab, welches Kriterium für ein konkretes Projekt am schwersten wiegt, funktionale Konsistenz, Ökosystem-Breite oder Bundle-Größe.

10. Zusammenfassung

Der Vergleich zwischen io-ts, Zod und Valibot zeigt drei unterschiedliche Antworten auf dieselbe Frage, wie Laufzeit-Validierung und TypeScript-Typen aus einer Quelle abgeleitet werden. io-ts passt am besten zu Teams, die bereits konsequent mit fp-ts arbeiten und Either-basierte Fehlerbehandlung als Standard etabliert haben. Zod bietet die breiteste Ökosystem-Integration und die niedrigste Einstiegshürde, weshalb es für die meisten Allzweck-Projekte die pragmatische Standardwahl bleibt.

Valibot gewinnt dort, wo Bundle-Größe messbar zählt, insbesondere in performance-kritischen Frontends mit striktem JavaScript-Budget, etwa in einem Hyvä-Kontext. Eine Migration zwischen Zod und Valibot ist meist mechanisch und risikoarm, während ein Wechsel zwischen io-ts und den beiden anderen Bibliotheken den kompletten Fehlerbehandlungs-Stil betrifft und entsprechend schrittweise geplant werden sollte.

11. FAQ: io-ts vs. Zod vs. Valibot