Tutorial1 de junho de 2026 | FlexyConsent

Consentimento de Cookies para Next.js, Gatsby e Sites Estáticos: Guia de Integração para Desenvolvedores

O Problema do Consentimento em Sites Estáticos

Frameworks modernos de JavaScript como Next.js, Gatsby e Nuxt.js introduziram uma mudança de paradigma em como as páginas web são construídas e entregues. As páginas são pré-renderizadas em tempo de build ou no servidor e depois hidratadas no cliente. Isso cria um desafio único para o consentimento de cookies: o banner de consentimento precisa estar pronto antes que qualquer script de rastreamento seja executado, mas a própria página pode já estar renderizada e em cache na borda.

Os CMPs tradicionais foram projetados para páginas em PHP renderizadas no servidor ou HTML simples, em que o documento é carregado linearmente de cima para baixo. Em um mundo de frameworks com code splitting, lazy loading e streaming server-side rendering, essas suposições deixam de valer. Acertar o consentimento nesses ambientes exige entender o pipeline de renderização.

Por que o Timing Importa Mais do que Você Imagina

Em uma página HTML padrão, colocar o script do CMP no <head> antes de outros scripts é simples. No Next.js App Router ou Gatsby, a situação é mais complexa:

O princípio central é este: o consentimento precisa ser estabelecido no nível do script, não no nível do componente. Um componente React que renderiza um banner de consentimento chega tarde demais se só se torna interativo após a hidratação.

Integração com Next.js App Router

O Next.js 13+ com o App Router introduziu uma nova forma de lidar com scripts. Aqui está a abordagem recomendada para integração de consentimento:

Passo 1: Carregar o Script do CMP no Layout Raiz

Use o componente Script do Next.js com a estratégia beforeInteractive no seu layout.tsx raiz. Isso diz ao Next.js para injetar o script no documento HTML inicial, antes do início da hidratação:

A estratégia beforeInteractive é crítica. A estratégia padrão afterInteractive carrega scripts após a hidratação, o que é tarde demais para o consentimento. Com beforeInteractive, o script do CMP é incluído no HTML renderizado no servidor e executa conforme a página é carregada.

Passo 2: Definir o Consentimento Padrão Antes das Tags do Google

Antes do seu snippet do Google Tag Manager ou gtag.js, inclua um script inline que defina os estados de consentimento padrão. Isso garante que, mesmo que o GTM carregue antes de o banner do CMP aparecer, ele respeite os padrões negados:

Esse script inline deve ser colocado no <head> do seu layout raiz, antes dos scripts do CMP e do GTM. No Next.js, você pode usar uma tag <script> normal dentro do elemento <head> do seu layout para esse fim.

Passo 3: Tratar Mudanças de Rota

Em navegação de single-page application, o script do CMP é carregado uma vez, mas as mudanças de rota não disparam um reload completo da página. Seu CMP precisa persistir nas navegações no lado do cliente. O FlexyConsent lida com isso automaticamente — uma vez carregado, permanece ativo em todas as mudanças de rota sem reinicialização.

Integração com Next.js Pages Router

Para projetos que ainda usam o Pages Router, a abordagem é semelhante, mas usa _document.tsx em vez do layout raiz. Coloque o script do CMP no componente <Head> da sua classe Document personalizada. A estratégia beforeInteractive funciona da mesma forma no Pages Router.

A principal diferença é que _document.tsx só é renderizado no servidor, então qualquer lógica de consentimento aqui é garantida no payload HTML inicial.

Integração com Sites Estáticos em Gatsby

O Gatsby gera HTML totalmente estático em tempo de build. Não há renderização no servidor em tempo de requisição, o que simplifica alguns aspectos, mas complica outros:

A abordagem em tempo de build do Gatsby significa que cada arquivo HTML no seu CDN incluirá o script de consentimento. Isso é, na verdade, ideal — não há lógica de servidor para falhar ou fazer cache incorretamente.

Considerações para Nuxt.js

O Nuxt.js (baseado em Vue) tem seus próprios padrões. No Nuxt 3, use o composable useHead ou a configuração de head em nuxt.config.ts para adicionar o script do CMP globalmente. O Nuxt suporta a opção body: false (que coloca scripts no head) e o atributo async para carregamento não bloqueante.

Para o modo de renderização no servidor do Nuxt, o mesmo princípio se aplica: o script do CMP precisa estar na resposta HTML inicial, não ser injetado dinamicamente por um componente Vue após o mount.

Evitando Layout Shift

Banners de consentimento são notórios por causar Cumulative Layout Shift (CLS), um Core Web Vital que afeta o ranqueamento em SEO. Quando um banner aparece depois que a página é renderizada, ele empurra o conteúdo para baixo ou o sobrepõe de forma inesperada.

Estratégias para minimizar CLS causado por banners de consentimento:

A Abordagem Agnóstica de Framework do FlexyConsent

O FlexyConsent foi projetado para funcionar com qualquer framework — ou sem framework algum — atuando no nível do script em vez do nível do componente. Eis por que isso importa:

Dica para desenvolvedores: O teste mais simples para verificar a integração correta do CMP é abrir a aba Network do seu navegador, filtrar por domínios do Google e recarregar a página. Nenhuma requisição ao Google deve disparar antes de o comando de padrão de consentimento aparecer no console. Se disparar, seu CMP está carregando tarde demais.

O plano gratuito do FlexyConsent suporta pageviews ilimitadas e funciona com Next.js, Gatsby, Nuxt, Astro, SvelteKit, Remix e HTML puro. A integração é a mesma em todos eles: uma tag de script, colocada corretamente.

← Blog Ler tudo →