React İle Zod Kütüphanesi Kullanarak Gelişmiş Form Doğrulaması Nasıl Yapılır?

Ön Hazırlık ve Gereksinimler

Bu rehberi takip edebilmek için temel düzeyde React ve TypeScript bilginizin olması gerekmektedir. Projenizde modern bir paket yöneticisi (npm, pnpm veya bun) kullanıyor olmalısınız. Ayrıca, form yönetimi için React dünyasında standart haline gelmiş react-hook-form kütüphanesini Zod ile entegre bir şekilde kullanacağız.

Gerekli paketleri projenize dahil etmek için terminalinizde aşağıdaki komutu çalıştırın:

npm install react-hook-form @hookform/resolvers zod

react-hook-form, form durumunu yönetirken performans optimizasyonu sağlar. @hookform/resolvers ise Zod şemalarımızı React Hook Form ile köprüleyen (adapter) kütüphanedir. Bu araçlar, formlarınızın hem istemci tarafında hem de tip düzeyinde doğrulanmasını sağlar.

Zod ile Veri Şeması Oluşturma

Doğrulama sürecinin ilk adımı, verinin nasıl görünmesi gerektiğini tanımlayan bir Zod şeması oluşturmaktır. Şema, verinin hangi alanlara sahip olduğunu, bu alanların hangi tipte olduğunu ve hangi kısıtlamalara tabi tutulacağını belirler.

import { z } from 'zod';

export const userSchema = z.object({
  username: z.string().min(3, "Kullanıcı adı en az 3 karakter olmalıdır."),
  email: z.string().email("Geçerli bir e-posta adresi giriniz."),
  age: z.number().min(18, "18 yaşından büyük olmalısınız."),
});

export type UserFormData = z.infer;

Burada z.object ile form nesnemizin yapısını oluşturduk. z.infer kullanımı, şemamızdan otomatik olarak TypeScript arayüzü (interface) türetmemizi sağlar. Böylece form verilerimiz her zaman şemamızla uyumlu kalır.

React Hook Form ve Zod Entegrasyonu

Şemamızı oluşturduktan sonra, bunu useForm kancasına (hook) bağlamamız gerekir. zodResolver, Zod şemasını React Hook Form'un anlayacağı bir formata dönüştürür. Bu entegrasyon sayesinde hata mesajları otomatik olarak yönetilir.

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { userSchema, UserFormData } from './schema';

const RegistrationForm = () => {
  const { register, handleSubmit, formState: { errors } } = useForm({
    resolver: zodResolver(userSchema),
  });

  const onSubmit = (data: UserFormData) => {
    console.log("Doğrulanan Veri:", data);
  };

  return (
    
      {/* Form alanları buraya gelecek */}
    
  );
};

resolver parametresi, her tuş vuruşunda veya form gönderiminde Zod şemasını çalıştırır. Eğer doğrulama başarısız olursa, errors nesnesi otomatik olarak doldurulur.

Form Bileşenlerini Oluşturma ve Hataları Gösterme

Kullanıcıya hata mesajlarını göstermek, iyi bir kullanıcı deneyimi (UX) için kritiktir. errors nesnesi, şemadaki anahtarlara karşılık gelen hata mesajlarını içerir.

  
  {errors.username && 
{errors.username.message}
}
  
  
  {errors.email && 
{errors.email.message}
}
  
  Kaydol

Burada register fonksiyonu, input elemanlarını React Hook Form'a bağlar. errors.username.message ifadesi, Zod şemasında tanımladığımız hata metnini ekrana basar.

Zod ile Gelişmiş Doğrulama Kuralları

Bazen basit tip kontrolleri yeterli olmaz. Örneğin, şifrelerin eşleşmesi veya karmaşık bir nesne yapısının doğrulanması gerekebilir. Zod, refine metodu ile özel doğrulama mantıkları eklemenize olanak tanır.

const passwordSchema = z.object({
  password: z.string().min(8),
  confirmPassword: z.string()
}).refine((data) => data.password === data.confirmPassword, {
  message: "Şifreler eşleşmiyor",
  path: ["confirmPassword"],
});

refine metodu, formun genel durumunu kontrol etmenize yardımcı olur. path özelliği, hatanın hangi alana bağlanacağını belirtir, böylece hata mesajını doğru inputun altında gösterebilirsiniz.

Karşılaştırma: Geleneksel Yöntem vs Zod

Güvenlik Uyarısı: İstemci tarafındaki (Client-side) doğrulama, kullanıcı deneyimini iyileştirmek içindir. Güvenlik için verileri mutlaka sunucu tarafında (Server-side) tekrar doğrulamalısınız. İstemci tarafı kodları manipüle edilebilir.

Sıkça Sorulan Sorular

Zod ile asenkron doğrulama (örneğin e-posta kontrolü) yapabilir miyim?

Evet, Zod refine veya superRefine içerisinde asenkron fonksiyonlar kullanarak veritabanı sorguları yapmanıza olanak tanır.

Neden Yup yerine Zod tercih etmeliyim?

Zod, TypeScript ile çok daha iyi entegre olur ve çalışma zamanında (runtime) tip çıkarımı konusunda daha modern ve performanslı bir yapı sunar.

Form verilerini göndermeden önce temizleyebilir miyim?

Zod'un transform metodu ile verileri doğrulamadan önce biçimlendirebilir veya temizleyebilirsiniz.

Hata mesajlarını nasıl yerelleştirebilirim (i18n)?

Zod şemasındaki mesaj alanlarına sabit metinler yerine çeviri kütüphanenizden gelen fonksiyonları atayabilirsiniz.

Büyük formlarda performans düşüşü olur mu?

React Hook Form, gereksiz re-render işlemlerini engellediği için Zod ile birlikte oldukça yüksek performanslı çalışır.

Sorumluluk Reddi: Bu makalede yer alan kod örnekleri eğitim amaçlıdır. Üretim ortamındaki uygulamalarınızda, kullanıcı verilerini işlerken XSS (Cross-Site Scripting) ve SQL Injection gibi saldırılara karşı gerekli güvenlik katmanlarını (sanitization ve parameterized queries) uyguladığınızdan emin olun.

Zod Şemalarını Custom Hook ile Modüler Hale Getirme

Büyük ölçekli React uygulamalarında, form doğrulama mantığını her bileşenin içinde tanımlamak kod tekrarına yol açar. Zod şemalarınızı ve react-hook-form konfigürasyonlarınızı merkezi bir useForm hook'u içerisinde toplamak, uygulama genelinde standart bir doğrulama yapısı kurmanızı sağlar.

Aşağıdaki örnekte, kullanıcı kayıt formu için özelleştirilmiş bir hook yapısını inceleyebilirsiniz:

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

const registerSchema = z.object({
  username: z.string().min(3, "Kullanıcı adı en az 3 karakter olmalı"),
  email: z.string().email("Geçerli bir e-posta girin")
});

export const useRegistrationForm = () => {
  return useForm({
    resolver: zodResolver(registerSchema),
    defaultValues: {
      username: '',
      email: ''
    }
  });
};

Zod ile Karmaşık Koşullu Doğrulamalar (Refinement)

Bazen bir alanın doğrulanması, başka bir alanın değerine bağlı olabilir. Zod'un refine metodu, şema düzeyinde karmaşık mantıksal kontroller yapmanıza olanak tanır. Örneğin, "şifre" ve "şifre tekrarı" alanlarının eşleşip eşleşmediğini kontrol etmek için aşağıdaki yapıyı kullanabilirsiniz:

const passwordSchema = z.object({
  password: z.string().min(8),
  confirmPassword: z.string()
}).refine((data) => data.password === data.confirmPassword, {
  message: "Şifreler eşleşmiyor",
  path: ["confirmPassword"],
});

Bu yöntem, formun submit edilmesinden önce verinin bütünlüğünü korumak için en güvenli yoldur. path parametresi sayesinde hata mesajının doğrudan hangi input alanının altında görüneceğini belirleyebilir, kullanıcı deneyimini optimize edebilirsiniz.

Form Doğrulama Süreçlerinde Hata Ayıklama İpuçları

Geliştirme aşamasında Zod şemalarının neden hata döndürdüğünü anlamak bazen zor olabilir. ZodError nesnesini yakalayarak konsolda detaylı inceleme yapabilirsiniz. Özellikle flatten() metodu, hataları okunabilir bir nesne yapısına dönüştürmek için idealdir:

try {
  registerSchema.parse(formData);
} catch (err) {
  if (err instanceof z.ZodError) {
    console.log(err.flatten().fieldErrors);
  }
}

Bu teknik, özellikle karmaşık iç içe geçmiş (nested) form yapılarında hangi alanın doğrulamadan geçemediğini hızlıca tespit etmenize yardımcı olur. Hataları fieldErrors ile gruplandırmak, hata mesajlarını UI üzerinde dinamik olarak eşleştirmeyi kolaylaştırır.

Sonuç

React ile Zod kullanarak form doğrulaması yapmak, projenizin bakımını kolaylaştırır ve tip güvenliğini garanti altına alır. Bu rehberde, temel şema kurulumundan gelişmiş doğrulama kurallarına kadar gerekli tüm adımları tamamladık. Bir sonraki adım olarak, oluşturduğunuz bu doğrulama mantığını bir "Custom Hook" içerisine alarak projenizin genelinde tekrar kullanılabilir hale getirebilirsiniz.