React Academy · Aula

Erros de hidratação: causas e correções

Identifique divergências entre o HTML do servidor e do cliente e corrija-as com suppressHydrationWarning.

Erros de hidratação: causas e correções é uma aula grátis de React Academy no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de React Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de React Academy inclui 4 aulas no total.

O que é um erro de hidratação?

Um erro de hidratação ocorre quando o HTML renderizado pelo servidor pelo React não corresponde ao DOM virtual que o React espera no cliente. O React registra um aviso e renderiza novamente o componente do zero, causando um lampejo.

Causa comum 1: valores aleatórios

Usar Math.random(), Date.now() ou crypto.randomUUID() durante a renderização produz valores diferentes no servidor e no cliente.

// 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 comum 2: APIs exclusivas do navegador

Ler localStorage, window.innerWidth ou navigator durante a renderização causa uma falha no servidor ou produz valores diferentes.

// 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 comum 3: formatação de data e hora

A formatação de datas sensível à localidade retorna strings diferentes no servidor (localidade UTC do Node) e no cliente (localidade do navegador).

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

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

Causa comum 4: aninhamento inválido de HTML

O React gera o HTML do cliente a partir do DOM virtual, mas o aninhamento inválido de HTML (por exemplo, <p> dentro de <p>) faz com que os navegadores reestruturem o DOM de forma diferente, causando divergências.

// 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 comum 5: renderização condicional baseada no estado

Os componentes que renderizam de forma diferente com base em um estado exclusivo do cliente (como a autenticação do usuário ou a largura da tela) apresentam divergências porque o servidor renderiza sem esse estado.

// 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

Use suppressHydrationWarning nos elementos em que as divergências são intencionais (por exemplo, marcações de tempo formatadas no cliente). Isso suprime o aviso apenas para esse elemento.

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

Importação dinâmica com ssr: false

No Next.js, use dynamic(fn, { ssr: false }) para impedir completamente a renderização de um componente no servidor — eliminando divergências de hidratação em componentes exclusivos do cliente.

import dynamic from 'next/dynamic';

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

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

Depuração de erros de hidratação

O React 18 registra mensagens detalhadas de erros de hidratação no modo de desenvolvimento, mostrando exatamente qual nó do DOM apresenta divergência. Use o DevTools do navegador para inspecionar o HTML do servidor e a árvore do React.

useId para identificadores estáveis

useId() gera identificadores estáveis e exclusivos, consistentes entre as renderizações do servidor e do cliente — use-o para pares de id/htmlFor e atributos ARIA.

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

Testes para erros de hidratação

Execute o aplicativo Next.js no modo de desenvolvimento (npm run dev) e observe o console do navegador. As divergências de hidratação aparecem como avisos vermelhos com rastreamentos da pilha de componentes.

Verificação rápida

Qual é a melhor correção para um componente que renderiza de forma diferente no servidor e no cliente por ler dados de localStorage?

Recapitulação

As divergências de hidratação resultam de: valores aleatórios, APIs exclusivas do navegador, formatação sensível à localidade, aninhamento inválido de HTML e renderização condicional exclusiva do cliente. Corrija-as com useId(), useEffect para estados exclusivos do cliente, suppressHydrationWarning para diferenças intencionais e dynamic({ ssr: false }) para componentes exclusivos do cliente.

Perguntas Frequentes

A aula “Erros de hidratação: causas e correções” é grátis?

Sim — o texto completo de “Erros de hidratação: causas e correções” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de React Academy, atualize para CoddyKit PRO. O curso de React Academy inclui 4 aulas no total.

O que vou aprender em “Erros de hidratação: causas e correções”?

Identifique divergências entre o HTML do servidor e do cliente e corrija-as com suppressHydrationWarning. Você pratica React Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar React Academy?

Nenhuma experiência prévia é necessária. React Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.

Quanto tempo leva a aula “Erros de hidratação: causas e correções”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de React Academy?

Sim. Cada aula de React Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

Como funciona o SSR do React internamente
Erros de hidratação: causas e correções
Hidratação seletiva e HTML em fluxo
Padrão de arquitetura de ilhas

← Voltar para React Academy