Tópico: Metadata dinâmica por página no Next.js

Cada página de um site precisa contar ao mecanismo de busca o que representa. Título, descrição, URL canônica, imagem de compartilhamento e outros metadados ajudam o Google a entender o conteúdo, enquanto Visitors e redes sociais usam essas informações ao exibirem um link.

No Next.js, a forma mais prática de tratar isso por rota é usar a API generateMetadata, disponível no App Router. A função recebe as parâmetros da rota, busca os dados necessários e devolve um objeto de metadados. Com isso, duas páginas do mesmo site podem ter títulos e descrições próprios, mesmo quando usam o mesmo layout.

Este conteúdo tem caráter informativo. Decisões técnicas devem ser tomadas com profissional especializado.

O que é metadata dinâmica no Next.js

Metadata são informações guardadas no cabeçalho de uma página, na área chamada <head> do documento HTML. Elas não aparecem como conteúdo principal, mas orientam mecanismos de busca, navegadores e plataformas de compartilhamento.

A metadata dinâmica é calculada durante o processamento da rota. Isso acontece, por exemplo, quando uma página representa um produto, um artigo ou um perfil. O Next.js pode consultar uma base de dados, uma API ou um arquivo de conteúdo para montar os metadados daquele endereço específico.

Um site de notícias podeillustrates o conceito:

• A rota /artigos/guia-nextjs exibe o título "Guia de Next.js para iniciantes&quot.
• A rota /artigos/seguranca-nextjs exibe o título "Segurança em aplicações Next.js&quot.
• A imagem social de cada artigo pode vir do arquivo de imagem associado ao conteúdo.

As páginas pertencem ao mesmo projeto e compartilham elementos visuais, mas cada uma apresenta sua própria identidade nos resultados de busca.

Metadata estática e metadata dinâmica

A metadata estática é escrita diretamente no arquivo de uma rota. Ela funciona bem quando todas as páginas têm a mesma finalidade e não dependem de conteúdo variável.

A metadata dinâmica entra em cena quando cada página precisa de dados diferentes. É o caso de um catálogo com milhares de produtos, um blog com artigos publicados por autores diferentes ou uma área de contas com perfis individuais.

A escolha não precisa ser uma regra absoluta. Um site pode combinar os dois formatos. Por exemplo, o layout principal define metadados padrão, e a rota de produto acrescenta dados específicos.

Metadata dinâmica com generateMetadata

O App Router usa arquivos dentro da pasta app. Cada pasta pode conter um arquivo page.tsx, que define a rota visível para o navegador, e um arquivo metadata.ts, responsável pelos metadados daquela seção.

A forma mais flexível é exportar generateMetadata. O Next.js executa essa função no servidor, monta o cabeçalho da página e entrega o resultado ao HTML final. Essa arquitetura evita expor dados sensíveis no navegador e funciona bem com busca durante a renderização.

Estrutura básica de uma rota

Imagine uma rota de produto definida em app/produtos/[slug]/page.tsx:

import type { Metadata } from 'next'

type Produto = {
  nome: string
  descricao: string
  imagem: string
}

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>
}): Promise<Metadata> {
  const { slug } = await params
  const produto = await buscarProduto(slug)

  if (!produto) {
    return {
      title: 'Produto não encontrado',
    }
  }

  return {
    title: produto.nome,
    description: produto.descricao,
    openGraph: {
      title: produto.nome,
      description: produto.descricao,
      images: [{ url: produto.imagem }],
    },
  }
}

A função buscarProduto representa uma consulta a uma API, a um banco de dados ou a um sistema de gestão de conteúdo. Ela não precisa ser definida no exemplo, pois varia de projeto para projeto.

O ponto central está no parâmetro params. Ele identifica qual item foi solicitado pela URL. Ao obter o slug, você busca o registro correspondente e devolve os metadados daquela página.

Por que params é uma Promise?

Nas versões mais recentes do Next.js, os parâmetros dinâmicos chegam como uma Promise no TypeScript. Por isso, o exemplo utiliza await params dentro de generateMetadata.

Essa mudança deslocou parte da lógica para uma etapa assíncrona explícita. O resultado é mais consistente com o restante do App Router, que já trabalha com APIs e fontes de dados acessadas durante a renderização.

Se você Maintainer um projeto criado com uma versão anterior, confira a documentação da versão instalada antes de copiar o exemplo. A forma de tipar params mudou entre algumas versões do Next.js.

O papel do arquivo metadata.ts

O arquivo metadata.ts define metadados padrão para uma seção inteira. Ele é útil para establish títulos padrão, descrições e URLs canônicas que serão herdadas pelas rotas filhas.

Exemplo:

import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: {
    default: 'Minha loja',
    template: '%s | Minha loja',
  },
  description: 'Produtos selecionados para o dia a dia.',
}

Com o template, uma página que informa apenas title: 'Tênis de corrida' aparece como "Tênis de corrida | Minha loja&quot. A herança também facilita a manutenção, porque você não precisa repetir o nome da marca em cada rota.

Quando generateMetadata e um arquivo metadata.ts coexistem, os campos retornados pela função dinâmica têm precedência sobre os metadados herdados do segmento pai.

Campos mais usados

O objeto retornado aceita várias opções. As mais úteis para SEO e compartilhamento social são:

• title, que define o título da página e pode usar um template herdado.
• description, que apresenta a descrição do conteúdo nos mecanismos de busca.
• alternates.canonical, que informa a URL preferida quando existem endereços equivalentes.
• robots, que controla indexação e acompanhamento por bots.
• openGraph, que reúne informações usadas pelo Facebook, LinkedIn e outras plataformas.
• twitter, que configura cartões para redes sociais.
• icons, que define favicons e ícones do site.
• metadataBase, que ajuda a resolver imagens e URLs relativas.

Nem toda página precisa preencher tudo. Uma boa estratégia é manter uma base consistente e alterar apenas o que realmente varia.

Exemplos práticos de metadata por rota

Página de artigo em um blog

Um blog costuma combinar uma rota principal com uma rota dinâmica. O arquivo app/blog/[slug]/page.tsx pode buscar o artigo e usar o mesmo conjunto de dados tanto no conteúdo quanto nos metadados.

import type { Metadata } from 'next'

async function buscarArtigo(slug: string) {
  const resposta = await fetch(
    `https://api.exemplo.com/artigos/${slug}`,
    { next: { revalidate: 3600 } },
  )

  if (!resposta.ok) {
    return null
  }

  return resposta.json()
}

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>
}): Promise<Metadata> {
  const { slug } = await params
  const artigo = await buscarArtigo(slug)

  if (!artigo) {
    return {
      title: 'Artigo não encontrado',
      description: 'O conteúdo solicitado não está disponível.',
    }
  }

  return {
    title: artigo.titulo,
    description: artigo.resumo,
    alternates: {
      canonical: `/blog/${artigo.slug}`,
    },
    openGraph: {
      type: 'article',
      title: artigo.titulo,
      description: artigo.resumo,
      images: [
        {
          url: artigo.imagemCapa,
          width: 1200,
          height: 630,
          alt: artigo.titulo,
        },
      ],
    },
  }
}

Nesse caso, o título, o resumo, a URL canônica e a imagem de compartilhamento são gerados a partir do artigo. O cache de uma hora evita repetir a consulta em cada requisição, mas o intervalo deve corresponder à frequência real das atualizações.

Página de produto em e-commerce

Lojas precisam diferenciar variantes, categorias e produtos. O generateMetadata pode montar o nome da marca com o nome do produto e usar uma descrição própria do catálogo.

export async function generateMetadata({
  params,
}: {
  params: Promise<{ id: string }>
}): Promise<Metadata> {
  const { id } = await params
  const produto = await consultarProduto(id)

  if (!produto) {
    return { title: 'Produto indisponível' }
  }

  return {
    title: `${produto.nome} | ${produto.marca}`,
    description: produto.descricaoSEO,
    openGraph: {
      title: `${produto.nome}, ${produto.marca}`,
      description: produto.descricaoSEO,
      images: [{ url: produto.imagemPrincipal }],
    },
  }
}

A descrição deve representar o produto com clareza. Evite repetir uma lista de palavras-chave ou adicionar frases que não aparecem na experiência do usuário.

Página com paginação ou filtros

URLs com filtros podem representar combinações diferentes de conteúdo. Isso exige cuidado para não criar páginas quase idênticas, uma prática conhecida como canonicalização incorreta.

Uma URL paginada pode ter uma página própria, com título como "Catálogo de tênis, página 2&quot. Filtros que produzem combinações ilimitadas devem seguir a estratégia definida para indexação. O ideal é bloquear ou canonicalizar variações que não tenham valor de busca autônomo.

Como integrar a metadata com os dados da página

Evite buscas duplicadas

Na prática, a página e a função de metadados podem precisar do mesmo produto ou artigo. Se cada uma faz uma requisição separada, você aumenta o trabalho do servidor sem necessidade.

Uma alternativa é usar cache para reutilizar a consulta durante a mesma renderização:

import { cache } from 'react'

const obterProduto = cache(async (slug: string) => {
  const resposta = await fetch(
    `https://api.exemplo.com/produtos/${slug}`,
  )

  if (!resposta.ok) {
    return null
  }

  return resposta.json()
})

Depois, generateMetadata e o componente da página chamam obterProduto. O React reaproveita o resultado durante a renderização, conforme a documentação de cache.

Outra opção é manter os dados no servidor e repassá-los ao componente que precisa. A escolha depende da estrutura do projeto, do tipo de fonte de dados e da necessidade de atualização em tempo real.

Respeite o tempo de atualização

Uma API pode fornecer dados em tempo real, enquanto um CMS pode oferecer revalidação sob demanda. A estratégia de cache precisa acompanhar o conteúdo.

• Para artigos, revalidação por intervalo costuma ser suficiente.
• Para estoque e preços, prefira uma atualização mais próxima do momento da consulta.
• Para páginas institucionais, os valores podem ser estáticos durante a compilação.
• Para conteúdo_campaign_eliminado, vale observar se o Next.js permite a revalidação por tag, em vez de rebuild completo.

Não use cache apenas para "acelerar" sem considerar que o usuário pode receber uma informação desatualizada. Preço, disponibilidade e status de pedido são exemplos em que o atraso pode causar frustração.

Valide o retorno da API

Dados externos podem estar incompletos, desatualizados ou fora do formato esperado. A função deve prever isso antes de montar o title e a description.

if (!produto?.nome) {
  return {
    title: 'Produto não encontrado',
    description: 'Confira a disponibilidade deste produto.',
  }
}

Evite erros por campos opcionais. Uma página sem produto também precisa de uma resposta coerente. O tratamento adequado melhora a estabilidade do site e facilita a leitura do código.

Metadata dinâmica e SEO

A metadata ajuda mecanismos de busca a entender cada página, mas não substitui conteúdo de qualidade. Se a URL existir, funcionar e exibir a mesma proposta declarada nos metadados, ela já começa com uma base consistente.

Título e descrição únicos

Páginas com o mesmo título competem entre si na busca. Em um catálogo, por exemplo, variações minúsculas do nome do produto podem ser específicas, desde que representem diferenças reais. Descrições repetidas, por outro lado, desperdiçam uma oportunidade de explicar o valor daquela página.

O título deve ser curto, legível e relevante. A descrição deve resumir o conteúdo em poucos caracteres. O Next.js não define um limite único para SEO, mas mecanismos de busca normalmente truncam os resultados conforme o dispositivo e a disponibilidade de espaço.

URL canônica

A URL canônica informa qual endereço deve ser considerado preferencial quando a mesma página aparece em outras rotas. Ela é útil em cenários com:

• Parâmetros de rastreamento em links externos.
• Versões com e sem barra final.
• Migrações de plataforma.
• URLs de filtro que repetem o conteúdo principal.

A URL canônica deve apontar para uma página real e rastreável. Não é uma ferramenta para empurrar páginas sem índice ou para esconder conteúdo relevante.

Dados estruturados

A metadata informa o básico sobre a página. Dados estruturados, implementados em JSON-LD, acrescentam contexto sobre artigos, produtos, receitas, eventos e outros tipos de conteúdo.

No Next.js, você pode inserir JSON-LD no componente da página ou gerar o dado a partir da mesma fonte usada pelo generateMetadata. A duplicação também pode ocorrer nesse cenário, portanto vale manter o exemplo organize a busca em uma função compartilhada.

Indexação e robots

Nem toda URL precisa aparecer nos resultados de busca. Páginas de busca interna, configurações, resultados de filtros e áreas restritas podem receber regras de indexação por meio do arquivo robots.txt, das tags robots ou do cabeçalho X-Robots-Tag.

A remoção do robots em uma página não apaga resultados já indexados. Paraar URLs antigas, você também precisa considerar a ferramenta de remoção de URL do mecanismo de busca ou uma resposta 404 ou 410 quando a página realmente não existir mais.

Erros comuns e como evitá-los

Definir a mesma metadata em todas as páginas

Quando generateMetadata ignora params e devolve sempre o mesmo título, cada rota acaba com uma identidade igual. Isso acontece principalmente em projetos copiados de um exemplo único, sem adaptação ao conteúdo dinâmico.

Revise se o slug, o identificador ou o segmento recebido está sendo usado na busca. Também vale observar os dados na resposta HTML, porque o navegador pode exibir uma página aparentemente correta enquanto o cabeçalho mantém o valor padrão.

Buscar dados em uma função desnecessária

generateMetadata é útil quando o conteúdo varia. Se a página About tem título fixo e não consulta nenhuma fonte, o uso de generateMetadata aumenta a complexidade sem agregar valor.

Nesse caso, prefira metadata.ts ou exporte metadata diretamente no arquivo da página.

Esquecer a tipagem de params

No App Router, rotas dinâmicas recebem parâmetros. Sem o tipo correto, o editor pode aceitar o código, mas os valores ainda precisam ser aguardados no formato usado pela versão instalada.

Sempre confirme a assinatura de generateMetadata na documentação oficial da versão do Next.js adotada no projeto.

Criar canonicalizações erradas

A URL canônica deve apontar para a versão principal da página. Configurar todas as rotas para a home, por exemplo, pode impedir a indexação de conteúdo importante. Também é preciso evitar canonicals que retornam erro 404.

Imagens relativas sem metadataBase

Quando a imagem social usa um caminho como /capas/artigo.jpg, o Next.js precisa saber a URL base do site para resolver o endereço completo. Defina metadataBase no nível raiz ou utilize URLs absolutas nas páginas.

export const metadata: Metadata = {
  metadataBase: new URL('https://www.exemplo.com'),
}

Confundir metadados com conteúdo visível

O title dentro de generateMetadata não cria um título visível na página. Ele preenche o cabeçalho do documento. Se a interface também precisa mostrar um título, use um componente separado, como um <h1>.

Expor dados sensíveis

Como generateMetadata roda no servidor, não é necessário transformar todos os dados em propriedades públicas do cliente. Evite colocar segredos, tokens ou informações pessoais dentro do objeto de metadados. O cabeçalho é público.

Boas práticas de organização

Centralize a configuração

Quando o site possui muitas rotas, manter metadados em arquivos separados facilita a leitura. Você pode seguir esta estrutura:

app/
  layout.tsx
  page.tsx
  metadata.ts
  produtos/
    metadata.ts
    [slug]/
      page.tsx
  blog/
    metadata.ts
    [slug]/
      page.tsx

O metadata.ts raiz define padrões. As subseções podem sobrescrever apenas o que precisa ser diferente. As funções dinâmicas cuidam dos itens individuais.

Crie funções auxiliares

Funções auxiliares podem padronizar a construção de títulos, descrições e dados de compartilhamento:

function metadadosDoArtigo(artigo: Artigo): Metadata {
  return {
    title: artigo.titulo,
    description: artigo.resumo,
    openGraph: {
      type: 'article',
      title: artigo.titulo,
      description: artigo.resumo,
      images: [{ url: artigo.imagemCapa }],
    },
  }
}

Isso reduz repetição, mas não transforma a função em uma caixa preta. O código continua simples de revisar e testar.

Monitore o resultado

A implementação correta precisa ser conferida no HTML e nas ferramentas de teste. O Google Search Console mostra como o Google interpretou títulos e descrições. O Rich Results Test verifica dados estruturados. Ferramentas de compartilhamento permitem conferir Open Graph.

O PageSpeed Insights também ajuda a avaliar desempenho, embora o tamanho da metadata e o custo da busca de dados possam afetar esse contexto. Como a recuperação de metadados ocorre durante a renderização no servidor, vale observar o tempo de resposta da rota, especialmente quando a API externa é lenta.

Comparativo entre as formas de declarar metadata

Uma arquitetura madura costuma combinar mais de uma abordagem. O importante é entender a precedência: o arquivo do segmento mais próximo tem prioridade sobre o arquivo do segmento pai, e os campos definidos na função dinâmica substituem os metadados herdados correspondentes.

Quando utilizar outra estratégia

O generateMetadata é a escolha natural para metadados baseados em rota e conteúdo. Há situações em que outra abordagem faz mais sentido.

Se todas as páginas compartilham os mesmos metadados, um metadata.ts na raiz reduz trabalho. Se o conteúdo é totalmente estático e conhecido no momento da compilação, exportar metadata diretamente na página também é suficiente.

Quando os dados mudam com frequência, o Next.js pode combinar revalidação erogate tags. Quando a página precisa de personalized em tempo real, a geração dinâmica pode ser mais adequada, embora traga custos e complexidade maiores.

Static Generation com dados dinâmicos

O Next.js pode gerar rotas estáticas em tempo de compilação quando você fornece os parâmetros. Isso funciona bem para um catálogo conhecido:

export async function generateStaticParams() {
  const produtos = await listarProdutos()

  return produtos.map((produto) => ({
    slug: produto.slug,
  }))
}

A função generateMetadata continua sendo usada para montar os metadados de cada página. A diferença está na forma como o HTML é gerado e atualizado. Se o catálogo recebe produtos novos com frequência, vale revisar a estratégia de revalidação.

Server Rendering sob demanda

Páginas renderizadas a cada requisição são úteis quando o conteúdo depende do usuário, do horário ou de uma condição operacional. A função de metadados pode rodar no mesmo fluxo, mas deve ser mantida rápida e resistente a falhas externas.

Client Components

Um componente marcado com 'use client' não deve ser usado para gerar metadata no servidor. A função generateMetadata e a exportação metadata pertencem ao contexto do App Router no servidor. A separação entre componentes cliente e servidor é importante para evitar erros e vazamento de dados.

Checklist para uma implementação correta

Antes de publicar, percorra esta lista:

• A função recebe e aguarda os parâmetros da rota dinâmica.
• O título muda conforme o conteúdo buscado.
• A descrição resume a página sem repetir textos genéricos.
• A URL canônica aponta para uma URL válida.
• A imagem de compartilhamento tem URL absoluta ou metadataBase configurado.
• Campos ausentes na API geram fallbacks previsíveis.
• O cache considera a frequência de atualização dos dados.
• A mesma busca não é repetida sem necessidade.
• Regras de indexação correspondem ao valor real da página.
• Dados estruturados, se existirem, correspondem ao conteúdo visível.
• Nenhum segredo aparece no cabeçalho público.
• O HTML final contém os metadados esperados.
• A tipagem corresponde à versão instalada do Next.js.
• Testes cobrem item existente, item ausente e falha temporária da API.

Esse roteiro reduz falhas frequentes. Também ajuda a separar problemas de conteúdo, como um título fraco, de problemas técnicos, como uma função que não aguarda params.

Perguntas Frequentes (FAQ)

O que é metadata dinâmica no Next.js?

É a geração de metadados de uma página a partir dos dados da rota. Com generateMetadata, o Next.js pode buscar um produto, artigo ou perfil e montar título, descrição e informações sociais diferentes para cada URL.

Qual é a diferença entre metadata e generateMetadata?\n

metadata é um valor estático definido no módulo. generateMetadata é uma função assíncrona usada quando os metadados dependem de parâmetros, APIs ou banco de dados. Ela pode acessar dados de forma mais flexível.

Como pegar o slug dentro de generateMetadata?\n

A função recebe um objeto com params. Em versões recentes do Next.js, você aguarda params antes de acessar o parâmetro. O valor é lido do segmento dinâmico, como [slug], e pode ser usado para consultar o conteúdo.

Posso usar generateMetadata em qualquer página?\n

Você pode usá-la em rotas do App Router, inclusive em segmentos dinâmicos. Em páginas totally estáticas, exportar metadata pode ser mais simples. A escolha depende da necessidade de consultar dados e montar valores diferentes.

A metadata dinâmica ajuda o SEO do site?\n

Ela auxilia mecanismos de busca a identificar cada página quando o título, a descrição e a URL correspondem ao conteúdo visível. A implementação é apenas uma parte do trabalho de SEO, que também envolve conteúdo, indexação, links e experiência do usuário.

O que acontece se a API falhar ao gerar os metadados?\n

A função deve tratar a falha e retornar um fallback seguro. Se a falha Makes a rota indisponível, avalie uma estratégia de cache, revalidação ou nova tentativa. Nunca exponha credenciais ou mensagens internas no cabeçalho público.

Conclusão

A metadata dinâmica por página permite que uma rota do Next.js represente cada conteúdo com título, descrição e dados sociais próprios. A API generateMetadata centraliza esse trabalho, enquanto metadata.ts mantém padrões consistentes entre seções.

O detalhe que mais influencia o resultado não está apenas no código da função. Busca correta, tratamento de ausência, organização dos arquivos, controle de cache e revisão do HTML importam tanto quanto a configuração dos campos.

Para um projeto menor, comece com uma rota dinâmica e uma função simples. Depois, observe a saída no navegador, valide com ferramentas de SEO e evolua a organização conforme aumenta o número de páginas. A metadata fica mais fácil de manter quando segue a mesma lógica dos dados que já alimentam a interface.

Se você precisa de ajuda para colocar isso em prática, a Baita Site tem uma equipe especializada em sites, e-commerce, sistemas e inteligência artificial, com domínio total de WordPress. Fale com a gente e veja como podemos acelerar o seu projeto.

Referências consultadas

• Documentação oficial do Next.js: Metadata e generateMetadata
• Documentação oficial do Next.js: API Metadata
• Documentação oficial do Next.js: Metadata Files
• Documentação oficial do Next.js: API Route Handlers
• Google Search Central: Understand the title link and snippet