8 min de leitura
Nossa homepage tinha 29 KB de nada
Um useSearchParams() embaixo de um <Suspense> na raiz transformou toda página do nosso site Next.js numa casca vazia pros crawlers. Como achei, corrigi e protegi.
- nextjs
- seo
- react
Eu estava auditando a landing page da Refer por dois lados ao mesmo tempo: lendo o código e baixando o site no ar do jeito que um crawler faria. Os dois me deram respostas opostas.
O código dizia que o conteúdo era renderizado no servidor: Next.js App Router, componentes React, nada de exótico. O site no ar dizia que o <body> estava vazio.
Os dois falavam a verdade sobre o que mostravam. Então olhei exatamente o que o servidor mandava: 29 KB de HTML e zero caractere de texto no <body>. Era isto que tinha lá dentro:
<body class="antialiased min-h-dvh flex flex-col">
<div class="flex-1"></div>
<template data-dgst="BAILOUT_TO_CLIENT_SIDE_RENDERING"></template>
<script src="/_next/static/chunks/…"></script>
…
</body>As 23 rotas do site estavam assim. No navegador, todas pareciam perfeitas.
Quem lê o seu HTML de verdade
O navegador baixa essa casca vazia, roda o JavaScript e preenche a página. Se você não estiver procurando, nunca vê o buraco. O Googlebot também renderiza JavaScript, numa segunda passada, então o Google acabou vendo o nosso conteúdo.
Com os crawlers de IA a história é outra. Quando a Vercel estudou o tráfego de crawlers na rede dela, no fim de 2024, nenhum dos grandes crawlers de IA renderizava JavaScript. As exceções eram o Gemini, do Google, que usa a infraestrutura do Googlebot, e o Applebot. O GPTBot e o ClaudeBot até baixam alguns arquivos de JavaScript, mas não rodam. Pra eles, nosso site era um <title> e mais nada.
Brinque com isto. A página é inventada, mas os três jeitos de servi-la são as três fases pelas quais o nosso site passou:
Um hook, todas as páginas
A causa eram oito linhas no layout raiz:
// app/layout.tsx, antes
<body className="antialiased min-h-dvh flex flex-col">
<Suspense fallback={<div className="flex-1" />}>
<UTMProvider>
<div className="flex-1">{children}</div>
<MobileFooter />
</UTMProvider>
</Suspense>
</body>O UTMProvider lê os parâmetros de campanha da URL (?utm_source=…) pra que o formulário de cadastro saiba de onde o visitante veio. Pra ler, ele chamava useSearchParams().
A documentação do Next.js explica o que isso faz: numa rota renderizada estaticamente, o useSearchParams() faz a árvore de client components até o <Suspense> mais próximo ser renderizada no cliente. A ideia é embrulhar num <Suspense> só o componentezinho que precisa da URL, pra que só ele espere o navegador. (Sem nenhum <Suspense> acima dele, o next build falha numa página estática, então embrulhar tudo é o jeito mais rápido de fazer o erro sumir.) O nosso embrulhava o {children}. Então o servidor renderizava o fallback, um <div className="flex-1" /> vazio, pra toda página, e deixava o resto pro JavaScript.
Nada reclamou. Lint, type-check e testes passavam, o navegador mostrava tudo certo e o CI fazia deploy em produção a cada merge. O <Suspense> já estava no layout quando o site entrou no nosso monorepo, no fim de abril. A correção saiu em 2 de setembro.
A correção nem precisou de <Suspense>. Capturar UTM só importa no navegador mesmo (os parâmetros ficam guardados pro formulário ler no envio), então o provider agora lê window.location no efeito que ele já tinha:
// hooks/useUTM.tsx, depois (simplificado)
useEffect(() => {
// Nada de useSearchParams(): aqui, em volta do {children}, ele tirava toda página do SSR.
const params = new URLSearchParams(window.location.search);
saveUTM(params);
}, [pathname]);Bug bônus: toda página dizia ser a home
Já que eu estava no layout, achei no metadata dele um alternates: { canonical: "/" }. As rotas filhas herdam o metadata do layout, a menos que sobrescrevam, e nenhuma das nossas sobrescrevia. Então o /for-organizations dizia aos buscadores: "sou uma cópia da home, indexe ela no meu lugar". Todas diziam.
E nem dava pra sobrescrever. Toda página era client component ("use client"), e o metadata só pode ser exportado de server components. Por que eram client components? Nenhuma das quatro páginas de marketing usava um único hook do React. Eram "use client" só porque usavam o motion.div do Framer Motion nas animações de scroll.
Então tirei a animação das páginas. O texto do hero virou um <h1> e um <p> simples, sem animação. As seções que já viviam nos próprios client components mantiveram a animação lá. O que sobrou foi pra um client component pequeno, o <Reveal>, que embrulha filhos renderizados no servidor. Sem nenhum código de animação, as páginas viraram server components, cada uma com o próprio título e a própria URL canônica. O layout raiz perdeu o canonical. (Essa virou regra no meu próprio site também: nunca coloque canonical no layout raiz.)
Texto no <body>, medido no HTML pré-renderizado:
| Página | Antes | Depois |
|---|---|---|
/ | 0 | 2.258 |
/about | 0 | 1.875 |
/for-organizations | 0 | 5.393 |
/for-your-career | 0 | 3.637 |
/terms (e mais 4 páginas legais) | 0 | 3.053 |
Medir é onde eu errei (duas vezes)
Na primeira vez que contei os marcadores de bailout que sobraram depois da correção, o grep -c disse um por página. Só que o grep -c conta linhas, e o Next.js manda o documento inteiro numa linha só. O grep -o … | wc -l conta ocorrências: dois.
Os dois eram inofensivos. Um era o SpeedInsights da Vercel, que se embrulha no próprio <Suspense>. O outro era um player de vídeo carregado com dynamic(…, { ssr: false }), de propósito, porque ele só funciona no navegador. Nenhum dos dois embrulha conteúdo da página. A página que você está lendo também tem um: o <Analytics /> da Vercel também chama useSearchParams(), mas dentro do próprio <Suspense fallback={null}>, que não embrulha mais nada. É o padrão do jeito certo. Então o número a acompanhar é quanto texto tem no body, não quantos marcadores existem.
O segundo erro veio minutos depois e foi mais engraçado: meu script disse que 107% do texto da home estava escondido. Elementos aninhados eram contados uma vez pra cada embrulho. Juntar os intervalos antes resolveu, e o número de verdade foi pior do que eu esperava.
79% da home estava em opacity:0
As animações de scroll eram assim:
<motion.div initial={{ opacity: 0, y: 20 }} whileInView={{ opacity: 1, y: 0 }}>O Framer Motion renderiza o estado initial no HTML do servidor como estilo inline, style="opacity:0;transform:translateY(20px)". Só o JavaScript tira isso, quando o elemento entra na tela. Depois que o servidor voltou a renderizar as páginas, 79% do texto da home estava dentro de elementos com opacity:0. Só 476 caracteres apareciam sem JavaScript.
Minha primeira explicação, que chegou até a virar comentário no código, foi que o Googlebot nunca rola a página, então o whileInView nunca dispara pra ele. Isso é só meio verdade. A documentação do Google diz mesmo que a Busca não interage com a página, então nada de rolar ou clicar. Mas o John Mueller, do Google, já explicou que o Googlebot renderiza com uma viewport bem alta no lugar, então o conteúdo que aparece ao entrar na viewport carrega. O Googlebot provavelmente viu esse texto.
O argumento que se sustenta é mais simples: o próprio HTML diz que a maior parte da página é invisível. É isso que recebe todo leitor que não roda o nosso JavaScript: um visitante num celular lento cujo bundle ainda está baixando, alguém com JavaScript desligado, um crawler que aplica estilos mas não roda scripts. Se um crawler ignora estilo inline é decisão dele. Prefiro não apostar nisso quando a correção não custa nada:
'use client';
import { motion } from 'motion/react'; // o pacote atual do Framer Motion
export function Reveal({ children }: { children: React.ReactNode }) {
return (
<motion.div initial={{ y: 20 }} whileInView={{ y: 0 }} viewport={{ once: true }} transition={{ duration: 0.6 }}>
{children}
</motion.div>
);
}Pros visitantes de verdade, o conteúdo continua subindo até o lugar. Só nunca começa invisível. Depois da mudança, 95–97% do texto da home e do /for-organizations fica visível no HTML, e 100% nas outras páginas. O que sobra é o verso de um card que vira, que deve mesmo ficar escondido.
Um guarda que nunca falhou não é um guarda
Esse bug foi pro ar porque nada estava olhando. Então o CI agora roda um verify:seo logo depois do next build, e o deploy em produção espera por ele. Ele lê o HTML pré-renderizado e falha quando:
- uma página tem menos texto no body do que o mínimo dela, com um erro que aponta a causa provável (um provider chamando
useSearchParams()acima do{children}); - mais de 15% do texto de uma página está dentro de
opacity:0; - uma página não tem exatamente um
<h1>; - o JSON-LD está faltando ou não faz parse;
- um canonical aponta pra qualquer lugar que não seja a própria página;
- uma rota existe no disco mas não está no manifesto que gera o sitemap.
Depois eu quebrei o output do build de propósito pra ver o guarda falhar. Um check que você nunca viu falhar pode não estar checando nada.
Teste o seu site
Esta é a mesma medição num script que você aponta pra qualquer URL. Node 18 ou mais novo, sem dependências:
// crawler-eye.mjs: o que recebe um crawler que não roda JavaScript?
// Uso: node crawler-eye.mjs https://example.com
const res = await fetch(process.argv[2], { headers: { 'user-agent': 'crawler-eye/1.0' } });
const html = await res.text();
const body = html.match(/<body[^>]*>([\s\S]*)<\/body>/)?.[1] ?? '';
const text = (s) =>
s.replace(/<(script|style)[\s\S]*?<\/\1>/g, '').replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
// Texto dentro de elementos com opacity:0. Junta os intervalos pra contar embrulhos aninhados uma vez só.
const ranges = [];
for (const m of body.matchAll(/<(\w+)[^>]*opacity:\s*0[;"][^>]*>/g)) {
const tags = new RegExp(`</?${m[1]}\\b[^>]*>`, 'g');
tags.lastIndex = m.index + m[0].length;
for (let depth = 1, t; (t = tags.exec(body)); ) {
depth += t[0].startsWith('</') ? -1 : 1;
if (depth === 0) { ranges.push([m.index, tags.lastIndex]); break; }
}
}
let hidden = 0, end = -1;
for (const [s, e] of ranges.sort((a, b) => a[0] - b[0])) {
if (e <= end) continue;
hidden += text(body.slice(Math.max(s, end), e)).length;
end = e;
}
const total = text(body).length;
const bailouts = html.split('BAILOUT_TO_CLIENT_SIDE_RENDERING').length - 1;
console.log(`${(Buffer.byteLength(html) / 1024).toFixed(0)} KB of HTML`);
console.log(`${total} characters of body text, ${hidden} of them inside opacity:0`);
console.log(`${bailouts} client-side rendering bailout marker(s)`);A nossa home hoje:
75 KB of HTML
2307 characters of body text, 105 of them inside opacity:0
2 client-side rendering bailout marker(s)Os 105 são o card que vira, e os dois marcadores são os inofensivos. É regex, não um parser de HTML de verdade, então trate como um teste rápido.
O mesmo bug, três vezes
Uma última coisa. O mesmo layout, com o mesmo bailout, tinha sido copiado e colado em outros dois codebases, um deles um repositório morto. Parte da minha primeira auditoria foi feita nessa cópia morta, por engano. O layout é um dos arquivos mais copiados de um projeto Next.js, o que faz dele o pior lugar pra esconder um bug. Arquive as cópias mortas, ou alguém vai consertar a errada.
A versão curta:
- Olhe o que o servidor manda (dê um
curl) e meça o texto no<body>, não os marcadores de bailout. - Nunca chame
useSearchParams()num componente que embrulha o{children}de um layout. Leiawindow.locationnum efeito, ou ponha um<Suspense>justo em volta do único componente que precisa dela. - Não defina canonical no layout raiz.
- Anime
transform, nãoopacity, nas revelações de scroll. - Ponha o check no CI, e quebre ele uma vez de propósito.
Respostas rápidas
Por que o useSearchParams() faz minha página Next.js renderizar no cliente? Numa rota renderizada estaticamente, o servidor não conhece a query string, então o Next.js renderiza no navegador os client components até o <Suspense> mais próximo. Se esse boundary embrulha o {children} de um layout, são todas as páginas. (Sem nenhum boundary, o build falha.)
O que significa BAILOUT_TO_CLIENT_SIDE_RENDERING no meu HTML? Marca um <Suspense> que renderizou o fallback no servidor e vai renderizar o conteúdo no navegador. Ter um não é necessariamente um problema; o que importa é o que ele embrulha. Confira quanto texto tem no seu <body>.
Os crawlers de IA rodam JavaScript? Na análise da Vercel de dezembro de 2024 sobre o tráfego da rede dela, nenhum dos grandes crawlers de IA rodava. O Gemini, que usa o Googlebot, e o Applebot eram as exceções. Renderize no servidor tudo o que você quer que eles leiam.
O Googlebot rola a página? Não. O Google diz que a Busca não interage com a página. Segundo o John Mueller, do Google, o Googlebot renderiza com uma viewport bem alta no lugar, então o conteúdo que aparece ao entrar na viewport ainda carrega.
Texto com opacity:0 é ruim pra SEO? Os buscadores não publicam como tratam isso. O certo é que o HTML marca esse texto como invisível pra tudo o que não roda o seu JavaScript. Animar transform no lugar não custa nada.
Fontes
- Next.js,
useSearchParams(docs da v15: renderização estática e Suspense). - Next.js, Metadata e
generateMetadata(só em server components; merge com layouts). - Vercel, The rise of the AI crawler (dezembro de 2024).
- Google Search Central, Fix lazy-loaded content.
- Search Engine Roundtable, Google tends to not watch for scroll events or click to load more buttons (John Mueller sobre a viewport alta, 2021).