Kurs Next.js · Moduł 6: Formularze i Server Actions

Walidacja formularzy z Zod

6 min czytania ·
W tej lekcji11

W Metropolis Quantum każdy system wymaga precyzyjnej walidacji danych - od terminali dostępowych po panele kontroli implantów. Zod to biblioteka walidacyjna zaprojektowana z myślą o TypeScript, która stała się standardem w ekosystemie Next.js. W przeciwieństwie do innych rozwiązań, Zod automatycznie generuje typy TypeScript na podstawie schematów walidacji, eliminując duplikację kodu.

Dlaczego Zod?

W roku 2150, systemy Metropolis Quantum wymagają niezawodnej walidacji danych. Zod wyróżnia się na tle innych bibliotek walidacyjnych (Yup, Joi) z kilku powodów:

  1. TypeScript-first - schematy Zod automatycznie generują typy, eliminując duplikację
  2. Zero zależności - lekka biblioteka (~10 KB gzipped)
  3. Standard Next.js - oficjalnie rekomendowany w dokumentacji Next.js
  4. Działa na serwerze i kliencie - idealne dla Server Actions

Instalacja i import

npm install zod
import { z } from 'zod';

Podstawowe schematy Zod

Zod oferuje zestaw metod do definiowania typów danych - jak cyfrowe DNA opisujące strukturę informacji w systemie:

import { z } from 'zod';

// Typy prymitywne
const nameSchema = z.string();
const ageSchema = z.number();
const isActiveSchema = z.boolean();

// Schema obiektu - łączymy typy w strukturę
const userSchema = z.object({
  name: z.string(),
  email: z.string().email(),
  age: z.number().int().positive(),
  isActive: z.boolean(),
});

Każdy z.string(), z.number(), z.boolean() to podstawowy blok budulcowy schematu. Metoda z.object() łączy je w kompleksową strukturę - jak schemat terminala w Metropolis Quantum.

Metody walidacji: parse i safeParse

Zod oferuje dwa sposoby walidacji danych:

import { z } from 'zod';

const schema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
});

// 1. parse() - rzuca wyjątek przy błędnych danych
try {
  const data = schema.parse({ name: "Neo", email: "neo@quantum.io" });
  console.log("Dane poprawne:", data);
} catch (error) {
  console.error("Błąd walidacji:", error);
}

// 2. safeParse() - NIE rzuca wyjątku, zwraca obiekt z wynikiem
const result = schema.safeParse({ name: "", email: "zly-email" });

if (result.success) {
  console.log("Dane:", result.data);
} else {
  console.log("Błędy:", result.error.errors);
  // [{ path: ["name"], message: "String must contain at least 2 character(s)" }, ...]
}

Zasada: Używaj safeParse() w formularzach i Server Actions (bezpieczniejsze), a parse() gdy chcesz szybko przerwać wykonanie przy błędnych danych.

Komunikaty błędów i reguły walidacji

Zod pozwala na precyzyjne definiowanie reguł walidacji z własnymi komunikatami - jak konfiguracja systemu bezpieczeństwa w terminalu:

import { z } from 'zod';

const registrationSchema = z.object({
  username: z.string()
    .min(3, { message: "Nazwa użytkownika musi mieć co najmniej 3 znaki" })
    .max(20, { message: "Nazwa użytkownika może mieć maksymalnie 20 znaków" }),
  email: z.string()
    .email({ message: "Nieprawidłowy format adresu email" }),
  age: z.number()
    .int({ message: "Wiek musi być liczbą całkowitą" })
    .min(13, { message: "Musisz mieć co najmniej 13 lat" }),
  password: z.string()
    .min(8, { message: "Hasło musi mieć co najmniej 8 znaków" })
    .regex(/[A-Z]/, { message: "Hasło musi zawierać wielką literę" })
    .regex(/[0-9]/, { message: "Hasło musi zawierać cyfrę" }),
  acceptTerms: z.boolean()
    .refine(val => val === true, {
      message: "Musisz zaakceptować warunki korzystania z systemu"
    }),
});

Metoda .refine() pozwala na definiowanie własnych, niestandardowych reguł walidacji - przydatne, gdy wbudowane metody nie wystarczają.

Inferowanie typów: z.infer

Jedną z najpotężniejszych cech Zod jest automatyczne generowanie typów TypeScript ze schematów. Nie musisz utrzymywać oddzielnych interfejsów:

import { z } from 'zod';

const implantSchema = z.object({
  id: z.string().uuid(),
  name: z.string().min(1),
  powerLevel: z.number().min(0).max(100),
  isActive: z.boolean(),
  tags: z.array(z.string()),
});

// Typ generowany automatycznie ze schematu
type Implant = z.infer<typeof implantSchema>;
// Odpowiednik ręcznego: { id: string; name: string; powerLevel: number; isActive: boolean; tags: string[] }

// Teraz typ i walidacja są ZSYNCHRONIZOWANE
function processImplant(data: Implant) {
  console.log(data.name); // TypeScript zna typ!
}

Dzięki z.infer masz jedno źródło prawdy - schemat definiuje zarówno walidację, jak i typ TypeScript.

Integracja z React Hook Form

Zod doskonale współpracuje z React Hook Form dzięki adapterowi zodResolver. To najczęściej spotykany wzorzec w aplikacjach Next.js:

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

// 1. Definiujemy schemat
const loginSchema = z.object({
  email: z.string()
    .email({ message: "Nieprawidłowy adres email" }),
  password: z.string()
    .min(8, { message: "Hasło musi mieć co najmniej 8 znaków" }),
});

// 2. Generujemy typ
type LoginForm = z.infer<typeof loginSchema>;

// 3. Używamy w komponencie
export default function LoginPage() {
  const {
    register,
    handleSubmit,
    formState: { errors, isSubmitting }
  } = useForm<LoginForm>({
    resolver: zodResolver(loginSchema), // Zod jako walidator
    defaultValues: { email: '', password: '' }
  });

  const onSubmit = async (data: LoginForm) => {
    // data jest już zwalidowane i typowane!
    console.log("Logowanie:", data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register('email')} placeholder="Email" />
      {errors.email && <p>{errors.email.message}</p>}

      <input {...register('password')} type="password" placeholder="Hasło" />
      {errors.password && <p>{errors.password.message}</p>}

      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? 'Logowanie...' : 'Zaloguj się'}
      </button>
    </form>
  );
}

Kluczowa linia to resolver: zodResolver(loginSchema) - łączy schemat Zod z systemem walidacji React Hook Form.

Reusable schematy i kompozycja

W dużych aplikacjach warto tworzyć reusable schematy, które można łączyć i rozszerzać:

import { z } from 'zod';

// Bazowy schemat adresu - używany w wielu miejscach
const addressSchema = z.object({
  street: z.string().min(1, "Ulica jest wymagana"),
  city: z.string().min(1, "Miasto jest wymagane"),
  postCode: z.string().regex(/^\d{2}-\d{3}$/, "Format: XX-XXX"),
});

// Schemat użytkownika - rozszerzamy o adres
const userSchema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
  address: addressSchema,                    // Zagnieżdżanie
  shippingAddress: addressSchema.optional(),  // Opcjonalny
});

// .merge() - łączenie dwóch schematów
const baseProfile = z.object({ name: z.string(), bio: z.string() });
const socialProfile = z.object({ twitter: z.string(), github: z.string() });
const fullProfile = baseProfile.merge(socialProfile);

// .extend() - dodawanie pól do istniejącego schematu
const adminUser = userSchema.extend({
  role: z.literal('admin'),
  permissions: z.array(z.string()),
});

type AdminUser = z.infer<typeof adminUser>;

Zaawansowane techniki: refine i superRefine

Metoda .refine() pozwala na walidację, której nie da się wyrazić deklaratywnie - np. porównanie dwóch pól:

import { z } from 'zod';

const passwordSchema = z.object({
  password: z.string().min(8),
  confirmPassword: z.string(),
}).refine(data => data.password === data.confirmPassword, {
  message: "Hasła nie są identyczne",
  path: ["confirmPassword"], // Błąd przypisany do pola confirmPassword
});

// superRefine - gdy potrzebujesz wielu błędów jednocześnie
const advancedSchema = z.object({
  accountType: z.enum(['personal', 'business']),
  personalId: z.string().optional(),
  companyId: z.string().optional(),
}).superRefine((data, ctx) => {
  if (data.accountType === 'personal' && !data.personalId) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: "ID osobiste jest wymagane dla konta osobistego",
      path: ['personalId'],
    });
  }
  if (data.accountType === 'business' && !data.companyId) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: "ID firmy jest wymagane dla konta biznesowego",
      path: ['companyId'],
    });
  }
});

Alternatywy: Yup i Joi

Zod to standard w ekosystemie Next.js, ale istnieją alternatywy:

  • Yup - popularna z Formik, deklaratywna składnia, ale wymaga ręcznych definicji typów TypeScript
  • Joi - potężna, bogata w funkcje, ale duża (~40 KB) i głównie serwerowa

Zod jest rekomendowany dla projektów Next.js, ponieważ łączy walidację z typami TypeScript i działa zarówno na serwerze, jak i kliencie.

Podsumowanie

Zod to niezbędne narzędzie w arsenale programisty Next.js:

  • z.string(), z.number(), z.object() - definiowanie schematów
  • parse() i safeParse() - walidacja danych
  • .min(), .email(), .regex() - reguły z komunikatami błędów
  • .refine() - niestandardowa walidacja
  • zodResolver - integracja z React Hook Form
  • z.infer<typeof schema> - automatyczne generowanie typów
Kod do tej lekcji: App.tsx
import React, { useState } from 'react';

// Symulacja walidacji z Zod - schematy, parse, safeParse, komunikaty bledow

// Uproszczony "Zod" do demonstracji (w prawdziwym projekcie obiekt z importujesz z pakietu zod)
interface ZodIssue { path: string[]; message: string }
interface ZodResult<T> { success: boolean; data?: T; error?: { issues: ZodIssue[] } }

const z = {
  string: () => {
    const rules: Array<{ type: string; value?: any; msg: string }> = [];
    const validator: any = {
      min(n: number, opt?: { message?: string }) { rules.push({ type: 'min', value: n, msg: opt?.message || `Min ${n} znakow` }); return validator; },
      max(n: number, opt?: { message?: string }) { rules.push({ type: 'max', value: n, msg: opt?.message || `Max ${n} znakow` }); return validator; },
      email(opt?: { message?: string }) { rules.push({ type: 'email', msg: opt?.message || 'Nieprawidlowy email' }); return validator; },
      regex(re: RegExp, opt?: { message?: string }) { rules.push({ type: 'regex', value: re, msg: opt?.message || 'Nieprawidlowy format' }); return validator; },
      _validate(val: string): string | null {
        if (typeof val !== 'string') return 'Wymagany string';
        for (const rule of rules) {
          if (rule.type === 'min' && val.length < rule.value) return rule.msg;
          if (rule.type === 'max' && val.length > rule.value) return rule.msg;
          if (rule.type === 'email' && !/\S+@\S+\.\S+/.test(val)) return rule.msg;
          if (rule.type === 'regex' && !rule.value.test(val)) return rule.msg;
        }
        return null;
      },
    };
    return validator;
  },
  coerce: {
    number: () => {
      const rules: Array<{ type: string; value?: any; msg: string }> = [];
      const validator: any = {
        min(n: number, opt?: { message?: string }) { rules.push({ type: 'min', value: n, msg: opt?.message || `Min ${n}` }); return validator; },
        max(n: number, opt?: { message?: string }) { rules.push({ type: 'max', value: n, msg: opt?.message || `Max ${n}` }); return validator; },
        int(opt?: { message?: string }) { rules.push({ type: 'int', msg: opt?.message || 'Wymagana liczba calkowita' }); return validator; },
        _validate(val: string): string | null {
          const num = Number(val);
          if (val === '' || isNaN(num)) return 'Wymagana liczba';
          for (const rule of rules) {
            if (rule.type === 'min' && num < rule.value) return rule.msg;
            if (rule.type === 'max' && num > rule.value) return rule.msg;
            if (rule.type === 'int' && !Number.isInteger(num)) return rule.msg;
          }
          return null;
        },
      };
      return validator;
    },
  },
  object: (shape: Record<string, any>) => ({
    safeParse(data: Record<string, string>): ZodResult<any> {
      const issues: ZodIssue[] = [];
      const parsed: any = {};
      for (const [key, validator] of Object.entries(shape)) {
        const err = validator._validate(data[key] || '');
        if (err) issues.push({ path: [key], message: err });
        else parsed[key] = data[key];
      }
      if (issues.length > 0) return { success: false, error: { issues } };
      return { success: true, data: parsed };
    },
    parse(data: Record<string, string>) {
      const result = this.safeParse(data);
      if (!result.success) throw new Error('Zod validation failed: ' + result.error!.issues.map(i => i.message).join(', '));
      return result.data;
    },
  }),
};

// --- SCHEMAT ZOD ---
// W prawdziwym projekcie obiekt z pochodzi z pakietu zod
const implantSchema = z.object({
  name: z.string()
    .min(2, { message: 'Nazwa musi miec co najmniej 2 znaki' })
    .max(50, { message: 'Nazwa moze miec max 50 znakow' }),
  email: z.string()
    .email({ message: 'Nieprawidlowy format email' }),
  powerLevel: z.coerce.number()
    .min(1, { message: 'Poziom mocy musi byc wiekszy od 0' })
    .max(100, { message: 'Poziom mocy nie moze przekraczac 100' }),
});

// type Implant = z.infer<typeof implantSchema>;

export default function ZodValidationDemo() {
  const [values, setValues] = useState({ name: '', email: '', powerLevel: '' });
  const [fieldErrors, setFieldErrors] = useState<Record<string, string>>({});
  const [result, setResult] = useState<{ type: 'success' | 'error'; data: string } | null>(null);
  const [mode, setMode] = useState<'safeParse' | 'parse'>('safeParse');

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    setFieldErrors({});
    setResult(null);

    if (mode === 'safeParse') {
      const res = implantSchema.safeParse(values);
      if (res.success) {
        setResult({ type: 'success', data: JSON.stringify(res.data, null, 2) });
      } else {
        const errs: Record<string, string> = {};
        for (const issue of res.error!.issues) {
          errs[issue.path[0]] = issue.message;
        }
        setFieldErrors(errs);
        setResult({ type: 'error', data: JSON.stringify(res.error!.issues, null, 2) });
      }
    } else {
      try {
        const data = implantSchema.parse(values);
        setResult({ type: 'success', data: JSON.stringify(data, null, 2) });
      } catch (err: any) {
        setResult({ type: 'error', data: err.message });
      }
    }
  };

  const inputStyle: React.CSSProperties = {
    width: '100%', padding: '10px', background: '#0d1117',
    border: '1px solid #333', borderRadius: 6, color: '#e0e0e0',
    fontFamily: 'monospace', fontSize: 13, boxSizing: 'border-box'
  };

  const schemaCode = `const implantSchema = z.object({
  name: z.string().min(2).max(50),
  email: z.string().email(),
  powerLevel: z.coerce.number().min(1).max(100),
});

type Implant = z.infer<typeof implantSchema>;`;

  return (
    <div style={{ background: '#0f0f23', minHeight: '100vh', padding: 20, color: '#e0e0e0', fontFamily: 'monospace' }}>
      <h1 style={{ color: '#64ffda' }}>Walidacja z Zod</h1>
      <p style={{ color: '#888', fontSize: 13, marginBottom: 12 }}>
        Przetestuj schemat Zod - wpisz dane i wybierz metode walidacji.
      </p>

      <pre style={{ background: '#0d1117', border: '1px solid #333', borderRadius: 8, padding: 12, fontSize: 11, color: '#ce93d8', marginBottom: 16 }}>
{schemaCode}
      </pre>

      <div style={{ display: 'flex', gap: 8, marginBottom: 16 }}>
        {(['safeParse', 'parse'] as const).map(m => (
          <button key={m} onClick={() => { setMode(m); setResult(null); setFieldErrors({}); }} style={{
            background: mode === m ? '#1565c0' : '#1a2744',
            color: '#fff', border: `1px solid ${mode === m ? '#64ffda' : '#333'}`,
            borderRadius: 6, padding: '6px 14px', cursor: 'pointer', fontFamily: 'monospace', fontSize: 12
          }}>
            schema.{m}()
          </button>
        ))}
      </div>

      <form onSubmit={handleSubmit} style={{ maxWidth: 400 }}>
        {(['name', 'email', 'powerLevel'] as const).map(field => (
          <div key={field} style={{ marginBottom: 12 }}>
            <label style={{ color: '#64ffda', fontSize: 12, display: 'block', marginBottom: 4 }}>
              {field}
            </label>
            <input
              value={values[field]}
              onChange={e => setValues(prev => ({ ...prev, [field]: e.target.value }))}
              placeholder={field === 'powerLevel' ? '1-100' : field === 'email' ? 'neo@quantum.io' : 'Neural Link'}
              style={{ ...inputStyle, borderColor: fieldErrors[field] ? '#f44336' : '#333' }}
            />
            {fieldErrors[field] && <div style={{ color: '#f44336', fontSize: 11, marginTop: 4 }}>{fieldErrors[field]}</div>}
          </div>
        ))}
        <button type="submit" style={{
          background: '#e91e63', color: '#fff', border: 'none', borderRadius: 6,
          padding: '10px 20px', cursor: 'pointer', fontFamily: 'monospace', width: '100%'
        }}>
          schema.{mode}(formData)
        </button>
      </form>

      {result && (
        <div style={{
          marginTop: 16, borderRadius: 8, padding: 12, maxWidth: 400,
          background: result.type === 'success' ? '#1b5e20' : '#3e1010',
          border: `1px solid ${result.type === 'success' ? '#4caf50' : '#f44336'}`
        }}>
          <div style={{ color: result.type === 'success' ? '#4caf50' : '#f44336', marginBottom: 4 }}>
            {result.type === 'success' ? 'Walidacja udana! Typowany wynik:' : mode === 'parse' ? 'parse() rzucil wyjatek:' : 'safeParse() zwrocil bledy:'}
          </div>
          <pre style={{ color: '#ccc', fontSize: 11, margin: 0, whiteSpace: 'pre-wrap' }}>{result.data}</pre>
        </div>
      )}
    </div>
  );
}

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Czym różni się metoda safeParse() od parse() w Zod?

Zadania praktyczne w grze

  • Edytor kodu

    Stwórz schemat Zod z walidacją pól (name, email, powerLevel) i zintegruj go z React Hook Form przez zodResolver

  • Układanie w pionie

    Ułóż kroki integracji Zod z React Hook Form w prawidłowej kolejności

  • Klikanie w kolejności

    Ułóż składnię importu biblioteki Zod

  • Edytor kodu

    Utwórz formularz kontaktowy z polami: name, email, message używając kontrolowanych komponentów i useState

  1. PytanieMetoda safeParse w Zod
  2. Zadanie z kodemPraktyka: Schemat walidacji Zod z zodResolver
  3. Ułóż w kolejnościKroki walidacji z Zod w React Hook Form
  4. Kliknij w kolejnościKolejność: import → { → z
  5. Zadanie z kodemPraktyka: Utwórz formularz kontaktowy z polami: name,

Przydatne artykuły