Kurs Next.js · Moduł 6: Formularze i Server Actions
Walidacja formularzy z Zod
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:
- TypeScript-first - schematy Zod automatycznie generują typy, eliminując duplikację
- Zero zależności - lekka biblioteka (~10 KB gzipped)
- Standard Next.js - oficjalnie rekomendowany w dokumentacji Next.js
- Działa na serwerze i kliencie - idealne dla Server Actions
Instalacja i import
npm install zodimport { 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ówparse()isafeParse()- walidacja danych.min(),.email(),.regex()- reguły z komunikatami błędów.refine()- niestandardowa walidacjazodResolver- integracja z React Hook Formz.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. 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