TL;DR: TypeScript-Typen verschwinden zur Laufzeit komplett. Zod gibt dir echte Runtime-Validierung, die deine Typen und deine Daten synchron hält — kein blindes Vertrauen mehr in API-Responses oder User-Input.

Zod – TypeScript-First Schema-Validierung

Zod ist eine TypeScript-First Schema-Deklarations- und Validierungsbibliothek. Schemas einmal definieren, Typen automatisch ableiten, zur Laufzeit validieren.

zod.dev

🤔 Das Problem: TypeScript lügt dich an

Wenn du schon eine Weile mit TypeScript arbeitest, kennst du das Gefühl: Du definierst ein sauberes Interface, tippst alles brav durch — und trotzdem knallt es zur Laufzeit. Warum? Weil TypeScript-Typen nur zur Compile-Zeit existieren. Sobald dein Code im Browser oder auf dem Server läuft, sind alle Typen weg. Einfach so. Puff.

Das heißt: Wenn deine API etwas anderes zurückgibt als erwartet, wenn ein User Quatsch in ein Formular tippt, oder wenn deine Umgebungsvariablen fehlen — TypeScript hat keine Ahnung davon. Es kompiliert fröhlich durch und lässt dich im Regen stehen.

interface User {
  id: number;
  name: string;
  email: string;
}

// Das kompiliert ohne Probleme...
const response = await fetch("/api/user/1");
const user = (await response.json()) as User;

// ...aber was, wenn die API { id: "abc", name: null } zurückgibt?
// TypeScript sagt: "Alles cool!" — Runtime sagt: 💥
console.log(user.email.toLowerCase()); // Cannot read properties of undefined

Das as User ist das Gefährlichste, was du in TypeScript schreiben kannst. Es ist kein Cast wie in Java oder C# — es ist ein Versprechen an den Compiler, das du nicht einhalten kannst. Du sagst: "Vertrau mir, das ist ein User." Und der Compiler glaubt dir blind.

Warum du nur noch TypeScript nutzen solltest

TypeScript bietet dir Typsicherheit, bessere Tooling-Unterstützung und weniger Bugs.

Disane.dev

⚠️ Warum as-Casts gefährlich sind

Lass uns das mal konkret durchspielen. Stell dir vor, du baust eine App, die Nutzerdaten von einer externen API holt:

// ❌ So machen es leider viele
async function getUser(id: string): Promise<User> {
  const res = await fetch(`/api/users/${id}`);
  return (await res.json()) as User; // "Trust me, bro"
}

// Was passiert, wenn die API-Antwort so aussieht?
// { id: 42, username: "max", mail: "[email protected]" }
// → name ist undefined, email ist undefined
// → TypeScript merkt NICHTS davon

Das Problem wird noch schlimmer, wenn du as mit komplexeren Strukturen verwendest. Du baust Logik auf falschen Annahmen auf, und der Fehler taucht erst drei Funktionsaufrufe später auf — oder schlimmer: gar nicht, und du schreibst kaputte Daten in die Datenbank.

🛡️ Enter Zod: Dein Runtime-Bodyguard

Zod ist eine TypeScript-first Schema-Validierungsbibliothek. Statt blind zu vertrauen, definierst du ein Schema, das zur Laufzeit prüft, ob deine Daten dem entsprechen, was du erwartest. Und das Beste: Zod leitet daraus automatisch den TypeScript-Typ ab — eine einzige Source of Truth.

import { z } from "zod";

// Schema definieren
const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
});

// TypeScript-Typ ableiten — kein doppeltes Pflegen!
type User = z.infer<typeof UserSchema>;

// Jetzt wird WIRKLICH validiert
async function getUser(id: string): Promise<User> {
  const res = await fetch(`/api/users/${id}`);
  const data = await res.json();
  return UserSchema.parse(data); // Wirft bei ungültigen Daten!
}

Installieren kannst du Zod ganz einfach:

npm install zod
# oder
pnpm add zod
# oder
yarn add zod

⚙️ Zod Basics: Die wichtigsten Primitiven

Zod bringt Validatoren für alle Standard-Typen mit — und jeder Validator ist chainable mit zusätzlichen Constraints:

import { z } from "zod";

// Strings mit Constraints
const nameSchema = z.string().min(2, "Name muss mindestens 2 Zeichen haben").max(100);
const emailSchema = z.string().email("Ungültige E-Mail-Adresse");
const urlSchema = z.string().url();
const uuidSchema = z.string().uuid();

// Zahlen mit Grenzen
const ageSchema = z.number().int().min(0).max(150);
const priceSchema = z.number().positive().finite();

// Booleans, Dates, Enums
const isActiveSchema = z.boolean();
const createdAtSchema = z.date();
const roleSchema = z.enum(["admin", "user", "moderator"]);

// Optionale und nullable Felder
const bioSchema = z.string().optional(); // string | undefined
const avatarSchema = z.string().nullable(); // string | null
const nicknameSchema = z.string().nullish(); // string | null | undefined

// Default-Werte
const pageSchema = z.number().default(1);
const limitSchema = z.number().default(20);

🏗️ Objekte und Arrays

Die wahre Stärke von Zod zeigt sich bei komplexen Strukturen:

const AddressSchema = z.object({
  street: z.string(),
  city: z.string(),
  zip: z.string().regex(/^\d{5}$/, "PLZ muss 5 Ziffern haben"),
  country: z.string().default("DE"),
});

const UserSchema = z.object({
  id: z.number().int().positive(),
  name: z.string().min(1),
  email: z.string().email(),
  role: z.enum(["admin", "user", "moderator"]),
  addresses: z.array(AddressSchema).min(1, "Mindestens eine Adresse benötigt"),
  tags: z.array(z.string()).default([]),
  metadata: z.record(z.string(), z.unknown()).optional(),
  createdAt: z.string().datetime(),
});

type User = z.infer<typeof UserSchema>;
// Das ergibt exakt den Typ, den du erwarten würdest — inklusive
// optionaler Felder, Defaults und verschachtelter Strukturen.

Du kannst auch Tupel und Unions definieren:

// Tupel: feste Länge, verschiedene Typen
const coordinatesSchema = z.tuple([z.number(), z.number()]);

// Discriminated Union: Der sichere Weg für verschiedene Varianten
const EventSchema = z.discriminatedUnion("type", [
  z.object({ type: z.literal("click"), x: z.number(), y: z.number() }),
  z.object({ type: z.literal("keypress"), key: z.string() }),
  z.object({ type: z.literal("scroll"), delta: z.number() }),
]);

type Event = z.infer<typeof EventSchema>;
// Event ist automatisch: { type: "click"; x: number; y: number } | { type: "keypress"; key: string } | ...

🔧 Schema-Komposition: Wiederverwenden statt Copy-Pasten

Einer der größten Vorteile von Zod ist die Kompositionsfähigkeit. Statt Schemas von Grund auf neu zu schreiben, kannst du bestehende Schemas erweitern, zusammenführen oder Teile davon extrahieren:

// Basis-Schema
const BaseUserSchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
});

// Erweitern mit extend()
const CreateUserSchema = BaseUserSchema.extend({
  password: z.string().min(8),
  confirmPassword: z.string(),
}).refine(
  (data) => data.password === data.confirmPassword,
  { message: "Passwörter stimmen nicht überein", path: ["confirmPassword"] }
);

// Schema für die Antwort — mit ID und Timestamps
const UserResponseSchema = BaseUserSchema.extend({
  id: z.number(),
  createdAt: z.string().datetime(),
  updatedAt: z.string().datetime(),
});

// Teilmengen mit pick() und omit()
const UserNameEmailSchema = UserResponseSchema.pick({ name: true, email: true });
const UserWithoutTimestampsSchema = UserResponseSchema.omit({ createdAt: true, updatedAt: true });

// Alles optional machen mit partial()
const UpdateUserSchema = BaseUserSchema.partial();
// Ergibt: { name?: string; email?: string }

// Zwei Schemas zusammenführen mit merge()
const ProfileSchema = z.object({ bio: z.string(), avatar: z.string().url() });
const FullUserSchema = UserResponseSchema.merge(ProfileSchema);

REST-APIs verstehen und nutzen

Was REST-APIs sind, wie sie funktionieren und wie du sie in deinen Projekten nutzt.

Disane.dev

💻 Praxis: API-Responses validieren

Jetzt wird's praktisch. Hier ein realistisches Beispiel, wie du Zod in einem echten Projekt einsetzt:

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

const PaginationSchema = z.object({
  page: z.number().int().positive(),
  perPage: z.number().int().positive(),
  total: z.number().int().nonnegative(),
  totalPages: z.number().int().nonnegative(),
});

const ProductSchema = z.object({
  id: z.string().uuid(),
  name: z.string(),
  price: z.number().positive(),
  currency: z.enum(["EUR", "USD", "GBP"]),
  inStock: z.boolean(),
  categories: z.array(z.string()),
  description: z.string().optional(),
});

const ProductListResponseSchema = z.object({
  data: z.array(ProductSchema),
  pagination: PaginationSchema,
});

type Product = z.infer<typeof ProductSchema>;
type ProductListResponse = z.infer<typeof ProductListResponseSchema>;

// API-Client mit Validierung
async function fetchProducts(page = 1): Promise<ProductListResponse> {
  const res = await fetch(`/api/products?page=${page}`);

  if (!res.ok) {
    throw new Error(`API error: ${res.status}`);
  }

  const json = await res.json();
  return ProductListResponseSchema.parse(json);
}

🚀 .parse() vs .safeParse(): Fehlerbehandlung richtig gemacht

Zod bietet zwei Wege zur Validierung — und du solltest wissen, wann du welchen nimmst:

const UserSchema = z.object({
  name: z.string(),
  age: z.number().min(0),
  email: z.string().email(),
});

// ❌ parse() — wirft eine Exception bei ungültigen Daten
try {
  const user = UserSchema.parse(unknownData);
  // user ist hier garantiert valid und korrekt typisiert
} catch (error) {
  if (error instanceof z.ZodError) {
    console.error("Validierung fehlgeschlagen:", error.issues);
    // [{ code: "invalid_type", expected: "string", received: "undefined", path: ["name"], message: "Required" }]
  }
}

// ✅ safeParse() — gibt ein Result-Objekt zurück (kein throw!)
const result = UserSchema.safeParse(unknownData);

if (result.success) {
  // result.data ist korrekt typisiert als User
  console.log(result.data.name);
} else {
  // result.error ist ein ZodError mit allen Details
  const formatted = result.error.format();
  console.log(formatted.name?._errors); // ["Required"]
  console.log(formatted.email?._errors); // ["Invalid email"]
}

Faustregel: Verwende .parse(), wenn ungültige Daten ein echter Fehler sind (z.B. kaputte API-Response). Verwende .safeParse(), wenn du mit ungültigen Daten rechnest und sie sinnvoll behandeln willst (z.B. Formular-Validierung, wo du dem User Fehlermeldungen anzeigen willst).

🌍 Praxis: Umgebungsvariablen validieren

Ein Klassiker: Deine App startet, aber eine wichtige Umgebungsvariable fehlt. Statt das drei Stunden später in Production zu merken, validierst du beim Start:

// env.ts
import { z } from "zod";

const EnvSchema = z.object({
  NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
  PORT: z.string().transform(Number).pipe(z.number().int().positive()),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32, "JWT_SECRET muss mindestens 32 Zeichen lang sein"),
  REDIS_URL: z.string().url().optional(),
  CORS_ORIGINS: z.string().transform((s) => s.split(",").map((o) => o.trim())),
  LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
});

// Beim App-Start validieren
function validateEnv() {
  const result = EnvSchema.safeParse(process.env);

  if (!result.success) {
    console.error("❌ Ungültige Umgebungsvariablen:");
    for (const issue of result.error.issues) {
      console.error(`  ${issue.path.join(".")}: ${issue.message}`);
    }
    process.exit(1);
  }

  return result.data;
}

export const env = validateEnv();
// env.PORT ist jetzt number, nicht string!
// env.CORS_ORIGINS ist string[], nicht string!

Beachte den .transform() + .pipe() Trick: process.env liefert immer Strings. Mit transform wandelst du den String in eine Zahl um, und mit pipe validierst du das Ergebnis nochmal.

Custom-Formulare an Google Spreadsheets anbinden mit Apps Script

Mit Google Apps Script kannst du jedes Google Spreadsheet in ein kostenloses Formular-Backend verwandeln.

Disane.dev

📝 Praxis: Formular-Validierung

Zod ist perfekt für Formularvalidierung — vor allem in Kombination mit Libraries wie React Hook Form:

import { z } from "zod";

const ContactFormSchema = z.object({
  firstName: z.string().min(2, "Mindestens 2 Zeichen"),
  lastName: z.string().min(2, "Mindestens 2 Zeichen"),
  email: z.string().email("Bitte gib eine gültige E-Mail ein"),
  phone: z.string().regex(/^\+?[\d\s-]{6,}$/, "Ungültige Telefonnummer").optional(),
  subject: z.enum(["support", "sales", "feedback", "other"]),
  message: z.string()
    .min(10, "Nachricht muss mindestens 10 Zeichen haben")
    .max(5000, "Nachricht darf maximal 5000 Zeichen haben"),
  acceptTerms: z.literal(true, {
    errorMap: () => ({ message: "Du musst die AGB akzeptieren" }),
  }),
});

type ContactForm = z.infer<typeof ContactFormSchema>;

// React Hook Form Integration
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";

function ContactPage() {
  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm<ContactForm>({
    resolver: zodResolver(ContactFormSchema),
  });

  const onSubmit = (data: ContactForm) => {
    // data ist hier komplett validiert und typisiert!
    console.log(data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("firstName")} />
      {errors.firstName && <span>{errors.firstName.message}</span>}
      {/* ... weitere Felder */}
    </form>
  );
}

NestJS – Ein progressives Node.js Framework

NestJS ist ein Framework für effiziente, skalierbare Node.js Server-Anwendungen mit nativem TypeScript-Support.

nestjs.com

NestJS: Server-Framework auf Steroide

NestJS ist ein mächtiges Server-Framework für Node.js mit TypeScript-First-Ansatz.

Disane.dev

🏢 Integration mit NestJS

Falls du NestJS verwendest (und wenn du meinen NestJS-Artikel gelesen hast, tust du das vielleicht), kannst du Zod statt class-validator für DTOs nutzen. Mit nestjs-zod geht das super smooth:

// dto/create-user.dto.ts
import { createZodDto } from "nestjs-zod";
import { z } from "zod";

const CreateUserSchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
  password: z.string().min(8).regex(
    /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/,
    "Passwort braucht Groß- und Kleinbuchstaben und eine Zahl"
  ),
  role: z.enum(["user", "admin"]).default("user"),
});

export class CreateUserDto extends createZodDto(CreateUserSchema) {}

// controller
import { Controller, Post, Body, UsePipes } from "@nestjs/common";
import { ZodValidationPipe } from "nestjs-zod";

@Controller("users")
export class UsersController {
  @Post()
  @UsePipes(ZodValidationPipe)
  create(@Body() dto: CreateUserDto) {
    // dto ist validiert!
    return this.usersService.create(dto);
  }
}

Der Vorteil gegenüber class-validator: Du hast ein einzelnes Schema, das sowohl den TypeScript-Typ als auch die Validierung definiert. Kein Dekorator-Chaos, keine doppelte Pflege.

🎨 Zod vs. die Alternativen

Meine Empfehlung: Für neue TypeScript-Projekte ist Zod die beste Wahl. Die Type Inference ist unschlagbar, die API ist intuitiv, und das Ökosystem wächst rasant. Yup ist okay, wenn du es schon verwendest — aber für Neues? Zod, ganz klar.

🧪 Bonus: Fortgeschrittene Patterns

Zum Schluss noch ein paar fortgeschrittene Techniken, die dir im Alltag helfen:

// 1. Preprocessing: Daten VOR der Validierung transformieren
const SearchParamsSchema = z.object({
  query: z.string().min(1),
  page: z.preprocess(
    (val) => (typeof val === "string" ? parseInt(val, 10) : val),
    z.number().int().positive()
  ),
  sort: z.enum(["name", "date", "price"]).default("date"),
});

// 2. Recursive Types: Baumstrukturen validieren
type Category = z.infer<typeof CategorySchema>;
const CategorySchema: z.ZodType<Category> = z.lazy(() =>
  z.object({
    id: z.string(),
    name: z.string(),
    children: z.array(CategorySchema).default([]),
  })
);

// 3. Custom Error Messages mit errorMap
const StrictStringSchema = z.string({
  required_error: "Dieses Feld ist erforderlich",
  invalid_type_error: "Muss ein Text sein",
}).min(1, "Darf nicht leer sein");

// 4. Branded Types: Typensicherheit auf dem nächsten Level
const UserId = z.string().uuid().brand<"UserId">();
const OrderId = z.string().uuid().brand<"OrderId">();

type UserId = z.infer<typeof UserId>;
type OrderId = z.infer<typeof OrderId>;

// Das verhindert, dass du versehentlich eine OrderId als UserId verwendest
function getUser(id: UserId) { /* ... */ }

const userId = UserId.parse("550e8400-e29b-41d4-a716-446655440000"); // ✅
const orderId = OrderId.parse("550e8400-e29b-41d4-a716-446655440001");
// getUser(orderId); // ❌ TypeScript-Fehler! OrderId !== UserId

💡 Fazit

TypeScript-Typen sind großartig für die Entwicklungserfahrung — aber sie schützen dich nicht vor der rauen Realität zur Laufzeit. Jede API-Response, jede Benutzereingabe, jede Umgebungsvariable ist potenziell "unsicher" — und genau da springt Zod ein.

Was du mitnehmen solltest:

• Vertraue niemals externen Daten — validiere alles, was von außen kommt
• as-Casts sind kein Schutz — sie sind ein Versprechen, das du nicht einhalten kannst
• Zod ist deine Single Source of Truth — ein Schema, ein Typ, eine Validierung
• .safeParse() für erwartete Fehler, .parse() für unerwartete
• Validiere am Rand deiner Anwendung — da, wo externe Daten reinkommen

Hör auf, deinen APIs blind zu vertrauen. Dein zukünftiges Ich wird es dir danken. 🚀