Hydratačný nesúlad v Nuxte: čo to je a ako ho nájsť

Čo znamená „Hydration completed but contains mismatches“, prečo vzniká pri serverovom vykresľovaní v Nuxte a ako vinníka nájsť a opraviť.

Tomáš Renčík4 min čítania
Ilustračný obrázok k článku: Hydratačný nesúlad v Nuxte: čo to je a ako ho nájsť
Obsah článku
  1. 1. Čo je hydratácia
  2. 2. Prečo je to problém
  3. 3. Najčastejšie príčiny
  4. 4. Ako vinníka nájsť
  5. 5. Ako to opraviť (správne)
  6. 6. Čo nerobiť
  7. 7. Úloha na precvičenie
  8. 8. Časté otázky
  9. 9. Na záver
  10. 10. Súvisiace články

Stručne: Hydratačný nesúlad nastane, keď server vykreslí stránku inak, než ju potom vykreslí prehliadač. Najčastejšie za ním sú hodnoty známe len v prehliadači — čas, časové pásmo, localStorage, veľkosť okna, téma — alebo dáta načítané inak na serveri a inak v prehliadači.

Ak robíte v Nuxte (alebo v inom frameworku, ktorý vykresľuje stránky na serveri), skôr či neskôr uvidíte v konzole hlášku:

Hydration completed but contains mismatches.

Stránka zvyčajne funguje, tak ju ľudia ignorujú. Nemali by. Vysvetlím, čo znamená a ako ju nájsť.

Čo je hydratácia

Pri vykresľovaní na serveri (SSR) sa stránka stane v dvoch krokoch:

  1. Server vyrobí hotové HTML a pošle ho do prehliadača. Človek hneď vidí obsah.
  2. Prehliadač stiahne JavaScript, Vue si stránku „prevezme“ a oživí ju — pripojí kliknutia, reaktivitu a podobne. Tomu sa hovorí hydratácia.

Pri hydratácii Vue očakáva, že HTML zo servera je presne to isté, čo by samo vykreslilo v prehliadači. Ak nie je, hlási nesúlad a problematické miesto prekreslí.

Prečo je to problém

  • Používateľ vidí bliknutie: najprv jedno (zo servera), potom druhé (z prehliadača).
  • V horšom prípade sa kliknutia pripoja k nesprávnym prvkom.
  • Nesúlad často prezrádza skutočnú chybu: server nevidel dáta, ktoré mal vidieť.

Najčastejšie príčiny

1. Veci, ktoré pozná len prehliadač. window, localStorage, veľkosť obrazovky, systémová téma (prefers-color-scheme). Server ich nepozná, tak kreslí „predvolene“, prehliadač potom inak.

2. Čas. Server beží v UTC, prehliadač v slovenskom čase. „Dobré ráno“ vs. „Dobrý večer“, dnešný dátum, relatívny čas „pred 5 minútami“.

3. Náhoda. Math.random() alebo generované ID, ktoré vyjdú na serveri inak ako v prehliadači.

4. Dáta, ktoré sa na serveri nenačítali. Na serveri volanie API zlyhalo (a chyba sa ticho zahodila), tak sa nakreslil prázdny alebo predvolený stav. V prehliadači sa dáta načítali a nakreslilo sa niečo iné. Toto je najzákernejšie, lebo lokálne všetko funguje a na produkcii nie.

5. Neplatné HTML. <div> vnútri <p>, tabuľka bez <tbody>. Prehliadač si HTML „opraví“ a Vue potom nesedí.

Ako vinníka nájsť

Krok 1: pozrite sa v režime vývoja. Produkčný build hlási len súhrn. Vo vývojovom režime Vue vypíše, ktorý prvok a aký obsah nesedí. Často je to hneď jasné.

Krok 2: napodobnite produkciu. Ak sa chyba ukazuje len na ostrom webe, zistite, čím sa líši: časové pásmo servera (TZ=UTC), iné dáta, prihlásený používateľ, cookies (napríklad zvolená téma), iná konfigurácia. Spustite lokálne čo najbližšie k nej.

Krok 3: porovnajte HTML zo servera s výsledkom. V prehliadači si pozrite zdrojový kód stránky (to je výstup servera) a porovnajte ho s tým, čo vidíte v DevTools po načítaní. Rozdiel je vinník.

Krok 4: skontrolujte, čo si Nuxt odovzdal. Nuxt posiela stav zo servera do prehliadača v „payloade“. Ak tam chýbajú dáta, ktoré čakáte, na serveri sa nenačítali.

Ako to opraviť (správne)

Veci len pre prehliadač vykreslite až po načítaní:

<ClientOnly>
  <PrepinacTemy />
  <template #fallback><span class="miesto-pre-prepinac" /></template>
</ClientOnly>

Dáta, ktoré sa načítajú až v prehliadači, majú na serveri aj v prehliadači rovnaký „načítavací“ stav:

const { data, status } = useFetch('/api/moja-praca', { server: false })
// status 'idle' aj 'pending' = kresli kostru, nie prázdny zoznam

Pri volaní vlastného API na serveri použite funkcie, ktoré prenesú kontext požiadavky (cookies, prihlásenie). V Nuxte useFetch alebo useRequestFetch(). Obyčajný $fetch volaný počas vykresľovania na serveri kontext nemá — a potom na serveri dostanete chybu alebo prázdne dáta, zatiaľ čo v prehliadači všetko funguje.

Čas a náhodu počítajte na jednom mieste — buď len v prehliadači, alebo ich pošlite zo servera ako hotovú hodnotu.

Čo nerobiť

Varovanie nepotláčajte a neobaľujte polovicu stránky do <ClientOnly>, len aby zmizlo. Stratíte tým výhody vykresľovania na serveri (rýchlosť, SEO) a skutočnú chybu len schováte.

Úloha na precvičenie

Vyrobte si nesúlad schválne, aby ste ho spoznali:

  1. Do komponentu dajte {{ new Date().getSeconds() }} a obnovte stránku. V konzole uvidíte varovanie — server a prehliadač vykreslili iné číslo.
  2. Opravte to: vypočítajte hodnotu až v onMounted alebo komponent obaľte do <ClientOnly>.
  3. Skúste druhý prípad: v komponente čítajte localStorage priamo v šablóne. Opäť nesúlad — a opäť ho opravte.

Keď raz uvidíte, ako chyba vzniká, v cudzom kóde ju nájdete za pár minút.

Časté otázky

Týka sa to aj aplikácie, ktorá beží len v prehliadači (SPA)?

Nie. Bez vykresľovania na serveri hydratácia neprebieha, takže ani nesúlad nevzniká. Preto sa chyba niekedy ukáže až vtedy, keď tú istú aplikáciu spustíte so serverovým vykresľovaním.

Je nesúlad bezpečnostný problém?

Sám osebe nie. Ale ak prezrádza, že server nevidí dáta používateľa, oplatí sa zistiť prečo.

Na záver

Hydratačný nesúlad je ako kontrolka v aute. Auto ide ďalej, ale niečo nie je v poriadku. Najčastejšie je to drobnosť. Niekedy však prezradí, že server nevidí dáta, ktoré vidieť má — a to už drobnosť nie je.

  • #Nuxt
  • #Vue
  • #SSR
  • #hydratácia
  • #ladenie