Yup JS - Walidacja formularzy, która działa (i nie irytuje)

Walidacja danych w formularzach decyduje nie tylko o jakości informacji, ale też o tym, czy użytkownik przejdzie przez proces bez frustracji. Biblioteka yup js pomaga opisać reguły w jednym miejscu i sprawdzić dane jeszcze zanim trafią dalej do aplikacji lub API. W tym tekście pokazuję, jak działa, kiedy naprawdę się opłaca i jak wykorzystać ją tak, by formularz był czytelny, szybki i mniej irytujący dla użytkownika.

Czym jest Yup i kiedy ma sens w frontendzie

Yup to biblioteka do opisywania schematów danych i sprawdzania, czy wartości pasują do tych schematów. W praktyce oznacza to, że zamiast pisać osobne warunki dla każdego pola, tworzę jeden spójny model danych: jakie typy są dozwolone, które pola są obowiązkowe, jak mają wyglądać zależności między nimi i co zrobić z danymi niepełnymi albo zapisanymi w nieidealnej postaci.

To rozwiązanie szczególnie dobrze pasuje do formularzy, bo właśnie tam pojawia się najwięcej drobnych reguł: e-mail ma mieć poprawny format, hasło ma mieć określoną długość, wiek ma być liczbą, a zgoda na regulamin ma być zaznaczona. Dla mnie największą zaletą jest to, że schemat działa jak jedno źródło prawdy. Jeśli formularz, walidacja i komunikaty korzystają z tego samego modelu, kod staje się wyraźnie łatwiejszy w utrzymaniu.

Warto też pamiętać, że Yup nie służy wyłącznie do „odrzucania złych danych”. Ta biblioteka umie również je przygotować, czyli np. oczyścić wejście z nadmiarowych spacji albo zrzutować wartość na właściwy typ. To ważne, bo frontend często dostaje dane wpisane przez człowieka, a człowiek nie wpisuje ich idealnie. Skoro wiadomo już, po co ta biblioteka istnieje, czas zobaczyć, jak dokładnie przebiega walidacja.

Jak działa schemat walidacji w praktyce

Najpierw definiuję schemat, a dopiero potem odpalam walidację. To brzmi banalnie, ale porządkuje cały proces: schema opisuje oczekiwany kształt danych, a metoda walidująca sprawdza, czy wartości spełniają reguły. W Yup mam do dyspozycji zarówno sprawdzanie, jak i transformacje, więc ten sam schemat może służyć do kontroli wejścia i do delikatnego „naprawiania” danych przed dalszym przetwarzaniem.

import * as yup from 'yup';

const schema = yup.object({
  email: yup.string().email('Podaj poprawny e-mail').required('E-mail jest wymagany'),
  age: yup
    .number()
    .typeError('Wiek musi być liczbą')
    .min(18, 'Rejestracja jest dostępna od 18 lat')
    .required('Podaj wiek'),
});

const data = await schema.validate(formData, {
  abortEarly: false,
  stripUnknown: true,
});

W tym fragmencie widać kilka istotnych rzeczy. `abortEarly: false` pozwala zebrać wszystkie błędy naraz, zamiast zmuszać użytkownika do poprawiania formularza po jednym problemie. Z kolei `stripUnknown: true` usuwa pola, których nie ma w schemacie, co bywa przydatne przy danych wysyłanych z zewnątrz albo przy rozbudowanych formularzach z ukrytymi polami.

Jest też ważna różnica między walidacją a transformacją. `validate()` sprawdza reguły, natomiast `cast()` konwertuje dane, na przykład zamienia tekstowy zapis liczby na prawdziwy typ number. W praktyce oznacza to, że mogę najpierw oczyścić wejście, a potem zdecydować, czy nadal jest poprawne. Jeśli dane pochodzą już z pewnego źródła, sens ma tryb `strict`, który wyłącza automatyczne przekształcenia i sprawdza wartość „taką, jaka jest”.

Na tym etapie najłatwiej zrozumieć, dlaczego Yup bywa wygodny w większych formularzach: reguły są czytelne, a zachowanie danych przewidywalne. Sam schemat jednak nie wystarcza, jeśli komunikacja z użytkownikiem jest zła, więc warto spojrzeć na UX.

Jak walidacja wpływa na doświadczenie użytkownika

Walidacja formularza nie powinna wyglądać jak kara za popełniony błąd. Dobra walidacja pomaga użytkownikowi przejść proces szybciej, a nie blokuje go na każdym kroku. Ja zwykle zaczynam od jednej zasady: komunikat ma mówić, co trzeba zrobić, a nie tylko informować, że coś jest nie tak.

Najlepiej działa walidacja osadzona w interfejsie, czyli blisko pola, którego dotyczy. Użytkownik nie powinien szukać błędu na górze strony ani zgadywać, o które pole chodzi. W formularzach mobilnych to ma jeszcze większe znaczenie, bo ekran jest mały, a przewijanie między komunikatem i polem szybko męczy.

• Pokazuj błąd przy polu, a nie wyłącznie w ogólnym banerze.
• Nie wyświetlaj wszystkich ostrzeżeń od pierwszej sekundy, jeśli użytkownik jeszcze nie zaczął wpisywać danych.
• Używaj prostych komunikatów, np. „Podaj poprawny adres e-mail”, zamiast „Nieprawidłowy format danych”.
• Przy dłuższych formularzach podpowiadaj reguły wcześniej, zwłaszcza dla hasła, numeru telefonu albo numeru dokumentu.
• Zadbaj o dostępność: komunikaty powinny być czytelne także dla osób korzystających z klawiatury i czytników ekranu.

Ważna jest też decyzja, kiedy w ogóle uruchamiać walidację. Zbyt agresywna kontrola na każdym znaku potrafi być bardziej szkodliwa niż pomocna, szczególnie przy polach złożonych. W praktyce sensowny kompromis to walidacja po opuszczeniu pola, przy wysyłce formularza albo po pierwszym błędzie w danym polu. Gdy te zasady są jasne, łatwiej zbudować konkretny formularz i sprawdzić je na przykładzie.

Przykład formularza rejestracji z realnymi regułami

W formularzu rejestracji najczęściej mam kilka pól, które zależą od siebie i które muszą być czytelnie komunikowane użytkownikowi. To dobry scenariusz dla Yup, bo od razu widać, czy schemat jest praktyczny, czy tylko efektowny na papierze. Poniżej pokazuję wersję, którą da się łatwo rozbudować w realnym projekcie.

import * as yup from 'yup';

const registrationSchema = yup.object({
  name: yup
    .string()
    .trim()
    .min(2, 'Imię powinno mieć co najmniej 2 znaki')
    .required('Podaj imię'),
  email: yup
    .string()
    .trim()
    .email('Podaj poprawny adres e-mail')
    .required('E-mail jest wymagany'),
  password: yup
    .string()
    .min(12, 'Hasło powinno mieć co najmniej 12 znaków')
    .matches(/[A-Z]/, 'Dodaj przynajmniej jedną wielką literę')
    .matches(/[0-9]/, 'Dodaj przynajmniej jedną cyfrę')
    .required('Hasło jest wymagane'),
  confirmPassword: yup
    .string()
    .oneOf([yup.ref('password')], 'Hasła muszą być identyczne')
    .required('Potwierdź hasło'),
  age: yup
    .number()
    .typeError('Wiek musi być liczbą')
    .min(18, 'Rejestracja jest dostępna od 18 lat')
    .required('Podaj wiek'),
  terms: yup
    .boolean()
    .oneOf([true], 'Musisz zaakceptować regulamin'),
});

Ten schemat robi kilka rzeczy naraz i właśnie to jest jego siła. `trim()` porządkuje tekst, `oneOf()` pilnuje zgodności pól zależnych, a `matches()` wzmacnia kontrolę nad hasłem bez rozrzucania reguł po komponentach. Z perspektywy UX ważne jest też to, że każdy komunikat można dopasować językowo do użytkownika. Dobrze napisany błąd nie brzmi jak wyjątek z logów, tylko jak jasna instrukcja.

W praktyce przy takim formularzu najczęściej pokazuję wymagania hasła od razu obok pola, a nie dopiero po błędzie. To zmniejsza liczbę nieudanych prób i skraca drogę do wysłania formularza. Przy bardziej złożonych przypadkach można pójść dalej i stosować reguły warunkowe, na przykład wymagać dodatkowego pola tylko wtedy, gdy użytkownik zaznaczy konkretną opcję. Przy takim zapisie naturalnie pojawia się pytanie, czy Yup jest najlepszym wyborem, czy tylko jednym z kilku sensownych.

Yup na tle Zoda i własnych reguł

Nie wybierałbym narzędzia wyłącznie dlatego, że jest popularne. W tym miejscu liczy się przede wszystkim styl pracy zespołu, stopień złożoności formularzy i to, jak bardzo kod ma być powiązany z TypeScript. Dla mnie Yup jest bardzo dobrym wyborem, gdy zależy mi na deklaratywnych schematach, walidacji warunkowej i szybkim opisaniu formularzy bez pisania wszystkiego od zera. Zod częściej wybieram tam, gdzie typy i inferencja stoją w samym centrum projektu. Własne reguły mają sens tylko wtedy, gdy logika jest mała, jednorazowa albo ekstremalnie niestandardowa.

W praktyce największą przewagą Yup jest to, że łączy czytelność z elastycznością. Nie wymaga budowania całego systemu walidacji od zera, ale daje więcej niż prosty zestaw `if`-ów. Jeśli natomiast projekt jest mocno typowany i zespół chce możliwie ścisłego powiązania typów z danymi wejściowymi, wtedy uczciwie rozważyłbym także inne podejście. Nawet dobry walidator można jednak zepsuć błędnym wdrożeniem, dlatego warto zamknąć temat listą typowych pułapek.

Najczęstsze błędy, które psują walidację

Najczęściej widzę nie problem z samą biblioteką, tylko z tym, jak zostaje wpięta w formularz. Złe komunikaty, zbyt wczesne błędy, brak spójności z backendem i nadmiar reguł potrafią zepsuć nawet dobrze napisany schemat. Poniżej zebrałem rzeczy, które najczęściej kosztują czas i nerwy.

• Zbyt agresywna walidacja na każdym znaku wpisywania, przez co formularz „krzyczy” zanim użytkownik skończy myśleć.
• Komunikaty pisane technicznym językiem, które informują o błędzie, ale nie pomagają go naprawić.
• Ignorowanie różnicy między `undefined`, `null` i pustym stringiem, co prowadzi do niespodziewanych wyników.
• Rozjazd między frontendem i backendem, przez który użytkownik poprawia formularz, a serwer i tak go odrzuca.
• Używanie `strict` lub transformacji bez zrozumienia, że zmieniają zachowanie danych, a nie tylko ich walidację.
• Brak testów dla schematów, zwłaszcza tam, gdzie pola zależą od siebie i zmieniają się warunkowo.

Jeśli miałbym wskazać jeden szczególnie kosztowny błąd, byłaby to niespójność między walidacją w interfejsie a walidacją po stronie API. Użytkownik może zaakceptować drobne utrudnienie, ale trudno mu zaakceptować sytuację, w której frontend mówi „jest dobrze”, a backend odrzuca ten sam zestaw danych. Taka sytuacja obniża zaufanie do całego procesu, nie tylko do formularza. Dlatego ostatni krok to nie kolejna reguła, lecz kilka praktycznych zasad, które dobrze mieć pod ręką przed wdrożeniem.

Co zabrać do własnego formularza, zanim napiszesz pierwszy schemat

Przed pierwszym wdrożeniem ustaliłbym cztery rzeczy: kiedy pokazuję błąd, jakie pola są naprawdę obowiązkowe, jakiego typu mają być dane i czy backend akceptuje dokładnie te same założenia. To zwykle oszczędza więcej czasu niż późniejsze poprawianie całego flow. W dobrze zaprojektowanym formularzu walidacja nie przeszkadza, tylko prowadzi użytkownika przez proces.

• Ustal moment wyświetlania komunikatu: blur, submit albo po przekroczeniu konkretnej długości wpisu.
• Napisz komunikaty po polsku tak, żeby były krótkie, konkretne i możliwe do wykonania.
• Rozdziel walidację techniczną od UX, bo to nie zawsze jest ten sam moment w interakcji.
• Przetestuj formularz na klawiaturze, w mobile i z błędnymi danymi, a nie tylko na ścieżce idealnej.
• Traktuj schemat jako element produktu, a nie tylko kod pomocniczy.

Jeżeli chcesz, żeby formularz był naprawdę wygodny, Yup powinien być tylko jednym z elementów większej decyzji o tym, jak użytkownik dostaje informację zwrotną. Dobrze napisany schemat porządkuje kod, ale dopiero sensowny UX sprawia, że całość działa bez tarcia.