Kategoria: Next.js, React i TypeScript

Next.js — 'Hydration failed' powodowany różnicami daty i strefy czasowej

Poradnik techniczny · Kacper Bernecki

Hydration failed w aplikacji Next.js często oznacza, że HTML wygenerowany po stronie serwera (SSR) różni się od tego, który React próbuje zainicjować w przeglądarce. Jedna z częstych, ale subtelnych przyczyn to różne reprezentacje daty lub strefy czasowej: serwer może renderować Date/Intl w strefie UTC lub na podstawie środowiska serwerowego, a klient — w strefie użytkownika. Gdy komponenty w renderze SSR zawierają tekstowe wartości dat (np. toLocaleString(), toISOString(), format z Intl.DateTimeFormat) wynikający HTML może zawierać inny napis niż po stronie klienta, co prowadzi do błędu hydratacji. Problem nasila się przy dynamicznych, zależnych od czasu elementach:

Jak rozpoznać przyczynę

Sprawdź, czy komponent renderuje Date/Intl bezpośrednio podczas SSR. Jeżeli używasz new Date() lub Date.now() w ciele komponentu, wartość może się różnić między budowaniem (SSG) a żądaniem czy klientem.

Porównaj tekstowy output: zwróć HTML z serwera (View Source) i porównaj z DOM po ładowaniu. Różnica w zapisie czasu (np. '2026-11-07T10:00:00Z' vs '2026-11-07 11:00:00') wskazuje na problem strefy.

Sprawdź użycie Intl.DateTimeFormat lub toLocaleString bez jawnej locale i options. Serwer (Node.js) i przeglądarki mogą domyślnie stosować różne locale lub timeZone, powodując inne renderowanie.

Rozwiązanie krok po kroku

1. Zlokalizuj komponenty renderujące datę: przeszukaj kod pod kątem toLocaleString, toISOString, Intl.DateTimeFormat, new Date() w plikach pages i komponentach SSR/SSG.

2. Zastąp bezpośrednie formatowanie dat deklaracją warunkową: renderuj neutralny placeholder podczas SSR i sformatuj datę po stronie klienta w useEffect lub po hydracji.

3. W przypadku konieczności stałego formatu użyj jawnego formatera: new Intl.DateTimeFormat('en-US',{ timeZone: 'UTC', hour12: false }) lub formatowania na backendzie, aby oba środowiska używały tej samej timeZone i locale.

4. Dla SSG/SSR rozważ serializację wartości jako liczby (timestamp) zamiast stringa; klient może odczytać timestamp i sformatować lokalnie bez różnic w strukturze DOM.

5. Jeśli używasz next/image lub meta tagów zawierających daty, wygeneruj je tak, by były deterministyczne — np. canonicalDate = new Date(date).toISOString() — i unikaj toLocaleString w HTML generado na serwerze.

6. Uruchom build lokalnie w trybie produkcyjnym (next build && next start) z takimi samymi zmiennymi środowiskowymi jak produkcja, aby powtórzyć warunki serwera i sprawdzić czy błąd występuje poza deweloperskim HMR.

Jak sprawdzić, czy problem zniknął

Test A: Otwórz stronę w przeglądarce, zapisz 'View Source' (HTML od serwera) i porównaj z innerText doc.body po pełnym załadowaniu; brak rozbieżności w miejscach dat oznacza poprawną hydratację.

Test B: Zmień timeZone w formaterze na inną (np. 'UTC' vs 'Europe/Warsaw') i sprawdź czy hydratacja znów rozbija się — jeśli tak, przyczyna była w niejawnej strefie.

Test C: Wprowadź placeholder SSR (np. '—') i po hydracji w useEffect nadpisz wartością sformatowaną; jeśli błąd znika, problem był w różnicach renderowania SSR vs klient.

Czego nie robić

Nie używaj toLocaleString() bez jawnego locale/timeZone w renderze SSR — efekt zależy od środowiska i może powodować hydratację.

Unikaj formatowania daty bezpośrednio w JSX przy SSR; zamiast tego użyj serializacji (timestamp) lub klientocentrycznego formatowania po hydracji.