React Academy · Lezione

Errori di hydration: cause e soluzioni

Individui le differenze tra l'HTML server e client e le risolva con suppressHydrationWarning.

Errori di hydration: cause e soluzioni è una lezione React Academy gratuita su CoddyKit. Questa è la lezione 2 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento React Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso React Academy include 4 lezioni in totale.

Che cos'è un errore di hydration?

Un errore di hydration si verifica quando l'HTML generato dal server da React non corrisponde al DOM virtuale che React si aspetta sul client. React registra un avviso ed esegue nuovamente il rendering del componente da zero, causando un flash.

Causa comune 1: valori casuali

L'utilizzo di Math.random(), Date.now() o crypto.randomUUID() durante il rendering produce valori diversi sul server e sul client.

// Bad — different on server vs client:
<div id={Math.random().toString()}>...</div>

// Fix — use useId() (stable across server/client):
import { useId } from 'react';
function Component() {
  const id = useId();
  return <div id={id}>...</div>;
}

Causa comune 2: API disponibili solo nel browser

La lettura di localStorage, window.innerWidth o navigator durante il rendering va in errore sul server o produce valori diversi.

// Bad — localStorage doesn't exist on server:
<div>{localStorage.getItem('theme')}</div>

// Fix — read in useEffect (client-only):
const [theme, setTheme] = useState('light');
useEffect(() => {
  setTheme(localStorage.getItem('theme') ?? 'light');
}, []);

Causa comune 3: formattazione di data e ora

La formattazione delle date in base alle impostazioni locali restituisce stringhe diverse sul server (impostazioni locali UTC/Node) e sul client (impostazioni locali del browser).

// Risky — locale may differ:
<time>{new Date().toLocaleDateString()}</time>

// Fix — use a consistent locale:
<time>{new Date().toLocaleDateString('en-US', { timeZone: 'UTC' })}</time>

Causa comune 4: annidamento HTML non valido

React genera l'HTML del client dal DOM virtuale, ma un annidamento HTML non valido (ad esempio, <p> all'interno di <p>) induce i browser a ristrutturare il DOM in modo diverso, causando discrepanze.

// Bad — browser auto-closes the nested <p>:
<p>Outer <p>Inner</p> text</p>

// Fix — use <div> or correct semantic elements:
<div>Outer <p>Inner</p> text</div>

Causa comune 5: rendering condizionale basato sullo stato

I componenti che eseguono il rendering in modo diverso in base a uno stato disponibile solo sul client (come l'autenticazione dell'utente o la larghezza dello schermo) non corrispondono, perché il server esegue il rendering senza quello stato.

// Bad — server renders 'Guest', client re-renders 'Alice' immediately:
<h1>{user?.name ?? 'Guest'}</h1>

// Fix — use a mounted guard to defer client-only rendering:
const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);
if (!mounted) return <h1>Guest</h1>; // match server output

suppressHydrationWarning

Utilizzi suppressHydrationWarning sugli elementi in cui le discrepanze sono intenzionali, ad esempio per i timestamp formattati sul client. Sopprime l'avviso solo per quell'elemento.

<time suppressHydrationWarning dateTime={isoDate}>
  {new Date(isoDate).toLocaleString()}
</time>

Importazione dinamica con ssr: false

In Next.js, utilizzi dynamic(fn, { ssr: false }) per impedire completamente il rendering di un componente sul server, eliminando le discrepanze di hydration per i componenti disponibili solo sul client.

import dynamic from 'next/dynamic';

const ClientOnlyChart = dynamic(() => import('./Chart'), { ssr: false });

export default function Dashboard() {
  return <ClientOnlyChart />; // only renders in the browser
}

Debug degli errori di hydration

In modalità di sviluppo, React 18 registra messaggi dettagliati sugli errori di hydration, mostrando la discrepanza esatta nel nodo DOM. Utilizzi i DevTools del browser per confrontare l'HTML del server con l'albero di React.

useId per ID stabili

useId() genera ID stabili e univoci, coerenti tra il rendering sul server e quello sul client. Lo utilizzi per le coppie id/htmlFor e per gli attributi ARIA.

function FormInput({ label }: { label: string }) {
  const id = useId();
  return (
    <div>
      <label htmlFor={id}>{label}</label>
      <input id={id} />
    </div>
  );
}

Test degli errori di hydration

Esegua l'app Next.js in modalità di sviluppo (npm run dev) e controlli la console del browser. Le discrepanze di hydration vengono visualizzate come avvisi rossi con lo stack di chiamate dei componenti.

Verifica rapida

Qual è la soluzione migliore per un componente che esegue il rendering in modo diverso sul server e sul client perché legge da localStorage?

Riepilogo

Le discrepanze di hydration derivano da: valori casuali, API disponibili solo nel browser, formattazione sensibile alle impostazioni locali, annidamento HTML non valido e rendering condizionale solo sul client. Le risolva con useId(), useEffect per lo stato solo client, suppressHydrationWarning per le differenze intenzionali e dynamic({ ssr: false }) per i componenti solo client.

Domande Frequenti

La lezione «Errori di hydration: cause e soluzioni» è gratuita?

Sì — il testo completo di «Errori di hydration: cause e soluzioni» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso React Academy, passa a CoddyKit PRO. Il corso React Academy include 4 lezioni in totale.

Cosa imparerò in «Errori di hydration: cause e soluzioni»?

Individui le differenze tra l'HTML server e client e le risolva con suppressHydrationWarning. Eserciti React Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare React Academy?

Non è richiesta alcuna esperienza precedente. React Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 2 di 4.

Quanto tempo richiede la lezione «Errori di hydration: cause e soluzioni»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione React Academy?

Sì. Ogni lezione React Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

← Torna a React Academy