SEO e Metadados

Q: Qual a diferença entre a exportação metadata e generateMetadata?

metadata é um objeto estático para páginas com metadados fixos (por exemplo, a página inicial). generateMetadata é uma função assíncrona para páginas onde os metadados dependem de dados dinâmicos (por exemplo, um post de blog). Ambos são exportados de page.tsx ou layout.tsx e são apenas para Server Components.

Q: O que é metadataBase e por que é necessário?

metadataBase define a URL base para todas as URLs de metadados relativas (imagens OG, URLs canônicas). Sem ele, URLs relativas em tags Open Graph quebrarão. Defina-o para sua URL de produção no layout raiz: metadataBase: new URL("https://myapp.com").

Q: Como funcionam sitemap.ts e robots.ts como convenções de arquivo?

Exportar uma função padrão de app/sitemap.ts a serve automaticamente em /sitemap.xml. Exportar uma função padrão de app/robots.ts a serve automaticamente em /robots.txt. Ambos podem ser assíncronos e buscar dados de um banco de dados.

Q: Armadilha: Client Components podem exportar metadata ou generateMetadata?

Não. A Metadata API só funciona em Server Components. metadata e generateMetadata devem ser exportados de page.tsx ou layout.tsx sem a diretiva "use client".

Q: Como adicionar dados estruturados JSON-LD a uma página?

Renderize uma tag no componente da página. Use o pacote schema-dts para objetos JSON-LD tipados.

Q: Como tipar os parâmetros de generateMetadata em TypeScript para Next.js 15+?

params é uma Promise no Next.js 15+ e deve ser aguardada.

Q: O que é ResolvingMetadata e como usá-lo?

É o segundo argumento para generateMetadata, fornecendo metadados pais resolvidos. Use-o para estender imagens Open Graph pais: const prev = (await parent).openGraph?.images ?? []. Isso permite que páginas filhas herdem e aumentem os metadados pais.

Q: Como lidar com sitemaps para sites com mais de 50.000 URLs?

A convenção sitemap.ts embutida não tem suporte de paginação. Implemente um índice de sitemap com múltiplos arquivos de sitemap usando Route Handlers. Cada arquivo de sitemap deve conter até 50.000 URLs por especificação do protocolo de sitemap.

// app/layout.tsx
import type { Metadata } from "next";
 
export const metadata: Metadata = {
  title: {
    default: "Meu App",
    template: "%s | Meu App",
  },
  description: "Uma aplicação web moderna construída com Next.js",
  metadataBase: new URL("https://myapp.com"),
  openGraph: {
    type: "website",
    locale: "pt_BR",
    siteName: "Meu App",
  },
  twitter: {
    card: "summary_large_image",
    creator: "@myapp",
  },
  robots: {
    index: true,
    follow: true,
  },
};
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="pt-BR">
      <body>{children}</body>
    </html>
  );
}

Metadados Dinâmicos com generateMetadata

// app/posts/[slug]/page.tsx
import type { Metadata, ResolvingMetadata } from "next";
import { notFound } from "next/navigation";
 
type Props = {
  params: Promise<{ slug: string }>;
};
 
export async function generateMetadata(
  { params }: Props,
  parent: ResolvingMetadata
): Promise<Metadata> {
  const { slug } = await params;
  const post = await db.post.findUnique({ where: { slug } });
 
  if (!post) {
    return {};
  }
 
  const parentMetadata = await parent;
  const previousImages = parentMetadata.openGraph?.images ?? [];
 
  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      title: post.title,
      description: post.excerpt,
      type: "article",
      publishedTime: post.createdAt.toISOString(),
      authors: [post.author.name],
      images: [
        {
          url: `/api/og?title=${encodeURIComponent(post.title)}`,
          width: 1200,
          height: 630,
          alt: post.title,
        },
        ...previousImages,
      ],
    },
    twitter: {
      card: "summary_large_image",
      title: post.title,
      description: post.excerpt,
    },
  };
}
 
export default async function PostPage({ params }: Props) {
  const { slug } = await params;
  const post = await db.post.findUnique({ where: { slug } });
 
  if (!post) notFound();
 
  return <article>{post.content}</article>;
}

Geração de Sitemap

// app/sitemap.ts
import type { MetadataRoute } from "next";
 
export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
  const posts = await db.post.findMany({
    select: { slug: true, updatedAt: true },
    orderBy: { updatedAt: "desc" },
  });
 
  const postEntries = posts.map((post) => ({
    url: `https://myapp.com/posts/${post.slug}`,
    lastModified: post.updatedAt,
    changeFrequency: "weekly" as const,
    priority: 0.8,
  }));
 
  const staticPages = [
    {
      url: "https://myapp.com",
      lastModified: new Date(),
      changeFrequency: "daily" as const,
      priority: 1.0,
    },
    {
      url: "https://myapp.com/about",
      lastModified: new Date(),
      changeFrequency: "monthly" as const,
      priority: 0.5,
    },
  ];
 
  return [...staticPages, ...postEntries];
}

Robots.txt

// app/robots.ts
import type { MetadataRoute } from "next";
 
export default function robots(): MetadataRoute.Robots {
  return {
    rules: [
      {
        userAgent: "*",
        allow: "/",
        disallow: ["/api/", "/admin/", "/dashboard/"],
      },
    ],
    sitemap: "https://myapp.com/sitemap.xml",
  };
}

Dados Estruturados JSON-LD

// app/posts/[slug]/page.tsx
import type { WithContext, Article } from "schema-dts";
 
function JsonLd({ data }: { data: WithContext<Article> }) {
  return (
    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }}
    />
  );
}
 
export default async function PostPage({ params }: Props) {
  const { slug } = await params;
  const post = await db.post.findUnique({ where: { slug } });
 
  if (!post) notFound();
 
  const jsonLd: WithContext<Article> = {
    "@context": "https://schema.org",
    "@type": "Article",
    headline: post.title,
    description: post.excerpt,
    datePublished: post.createdAt.toISOString(),
    dateModified: post.updatedAt.toISOString(),
    author: {
      "@type": "Person",
      name: post.author.name,
    },
  };
 
  return (
    <>
      <JsonLd data={jsonLd} />
      <article>{post.content}</article>
    </>
  );
}

Imagem OG Dinâmica

// app/api/og/route.tsx
import { ImageResponse } from "next/og";
import { NextRequest } from "next/server";
 
export const runtime = "edge";
 
export async function GET(request: NextRequest) {
  const title = request.nextUrl.searchParams.get("title") ?? "Meu App";
 
  return new ImageResponse(
    (
      <div
        style={{
          fontSize: 60,
          color: "white",
          background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
          width: "100%",
          height: "100%",
          display: "flex",
          alignItems: "center",
          justifyContent: "center",
          padding: 60,
          textAlign: "center",
        }}
      >
        {title}
      </div>
    ),
    {
      width: 1200,
      height: 630,
    }
  );
}

Análise Detalhada

Como Funciona

A Metadata API é a forma principal de definir tags <head> no App Router. Exporte um objeto metadata ou uma função generateMetadata de page.tsx ou layout.tsx.
Metadados se mesclam na árvore de componentes. Metadados filhos substituem metadados pais. O padrão title.template no layout raiz ("%s | Meu App") é aplicado aos títulos das páginas filhas.
generateMetadata recebe metadados pais resolvidos através do segundo argumento. Isso permite estender imagens Open Graph pais ou outros valores herdados.
sitemap.ts e robots.ts são convenções de arquivo especiais. O Next.js os serve em /sitemap.xml e /robots.txt automaticamente.
metadataBase define a URL base para todas as URLs de metadados relativas (imagens Open Graph, URLs canônicas). Sempre defina-o no layout raiz.
ImageResponse de next/og gera imagens Open Graph dinâmicas usando JSX na edge. Ele usa Satori internamente, que suporta um subconjunto de CSS (apenas flexbox, sem grid).

Variações

Múltiplos Sitemaps (Sites Grandes):

// app/sitemap/[id]/route.ts
import { NextRequest } from "next/server";
 
export async function GET(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const page = parseInt(id, 10);
  const perPage = 50000;
 
  const posts = await db.post.findMany({
    skip: page * perPage,
    take: perPage,
    select: { slug: true, updatedAt: true },
  });
 
  const xml = `<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  ${posts.map((post) => `
  <url>
    <loc>https://myapp.com/posts/${post.slug}</loc>
    <lastmod>${post.updatedAt.toISOString()}</lastmod>
  </url>`).join("")}
</urlset>`;
 
  return new Response(xml, {
    headers: { "Content-Type": "application/xml" },
  });
}

URLs Canônicas:

export const metadata: Metadata = {
  alternates: {
    canonical: "/posts/my-post",
    languages: {
      "en-US": "/en/posts/my-post",
      "de-DE": "/de/posts/my-post",
    },
  },
};

Notas de TypeScript

Importe Metadata e ResolvingMetadata de "next" para inferência de tipo completa.
MetadataRoute.Sitemap é um array de objetos com url, lastModified, changeFrequency e priority.
Use o pacote schema-dts para dados estruturados JSON-LD tipados.
Os parâmetros de generateMetadata são assíncronos no Next.js 15+ (mesmo padrão Promise<{ slug: string }> das páginas).

Armadilhas

generateMetadata é executado antes do componente da página. Sua busca de dados é dedupicada com a busca da página se a mesma URL for solicitada, mas a função em si é executada separadamente.
metadataBase deve ser uma URL absoluta. URLs relativas em imagens Open Graph quebrarão sem ele.
Client Components não podem exportar metadados. O objeto metadata e a função generateMetadata só funcionam em Server Components (page.tsx e layout.tsx).
ImageResponse suporta apenas flexbox. CSS Grid, position: absolute (com exceções) e muitas propriedades CSS não são suportadas pelo Satori.
Arquivos de sitemap devem retornar todas as URLs. Não há paginação embutida. Para sites com mais de 50.000 URLs, implemente um índice de sitemap com múltiplos arquivos de sitemap manualmente.
title.template se aplica apenas a páginas filhas, não à página onde é definido. A própria página usa title.default.

Alternativas

Abordagem	Prós	Contras
Metadata API (embutida)	Type-safe, automática, co-localizada	Não pode ser usada em Client Components
Pacote `next-seo`	API familiar da era Pages Router	Redundante com a Metadata API embutida
Tags `<head>` manuais	Controle total	Sem segurança de tipo, fácil de esquecer tags
`schema-dts` para JSON-LD	Dados estruturados tipados	Dependência extra
Pacote `next-sitemap`	Geração automática, suporte ISR	Dependência extra, sobrecarga de configuração

FAQs

Qual a diferença entre a exportação `metadata` e `generateMetadata`?

metadata é um objeto estático para páginas com metadados fixos (por exemplo, a página inicial).
generateMetadata é uma função assíncrona para páginas onde os metadados dependem de dados dinâmicos (por exemplo, um post de blog).
Ambos são exportados de page.tsx ou layout.tsx e são apenas para Server Components.

Como funciona a mesclagem de metadados na árvore de componentes?

Metadados filhos substituem metadados pais para os mesmos campos.
O title.template no layout raiz (por exemplo, "%s | Meu App") é aplicado aos títulos das páginas filhas.
title.template se aplica apenas a páginas filhas, não à página onde é definido.

O que é `metadataBase` e por que é necessário?

metadataBase define a URL base para todas as URLs de metadados relativas (imagens OG, URLs canônicas).
Sem ele, URLs relativas em tags Open Graph quebrarão.
Defina-o para sua URL de produção no layout raiz: metadataBase: new URL("https://myapp.com").

Como funcionam `sitemap.ts` e `robots.ts` como convenções de arquivo?

Exportar uma função padrão de app/sitemap.ts a serve automaticamente em /sitemap.xml.
Exportar uma função padrão de app/robots.ts a serve automaticamente em /robots.txt.
Ambos podem ser assíncronos e buscar dados de um banco de dados.

Armadilha: Client Components podem exportar `metadata` ou `generateMetadata`?

Não. A Metadata API só funciona em Server Components.
metadata e generateMetadata devem ser exportados de page.tsx ou layout.tsx sem a diretiva "use client".

Quais limitações de CSS o `ImageResponse` (Satori) tem para imagens OG dinâmicas?

Apenas o layout flexbox é suportado; CSS Grid não funciona.
position: absolute tem suporte limitado.
Muitas propriedades CSS não são suportadas; mantenha os estilos das imagens OG simples.

Como adicionar dados estruturados JSON-LD a uma página?

<script
  type="application/ld+json"
  dangerouslySetInnerHTML={{
    __html: JSON.stringify(jsonLdObject),
  }}
/>

Renderize uma tag <script type="application/ld+json"> no componente da página.
Use o pacote schema-dts para objetos JSON-LD tipados.

Como tipar os parâmetros de `generateMetadata` em TypeScript para Next.js 15+?

import type { Metadata, ResolvingMetadata } from "next";
 
type Props = {
  params: Promise<{ slug: string }>;
};
 
export async function generateMetadata(
  { params }: Props,
  parent: ResolvingMetadata
): Promise<Metadata> {
  const { slug } = await params;
  // ...
}

params é uma Promise no Next.js 15+ e deve ser aguardada.

O que é `ResolvingMetadata` e como usá-lo?

É o segundo argumento para generateMetadata, fornecendo metadados pais resolvidos.
Use-o para estender imagens Open Graph pais: const prev = (await parent).openGraph?.images ?? [].
Isso permite que páginas filhas herdem e aumentem os metadados pais.

Como lidar com sitemaps para sites com mais de 50.000 URLs?

A convenção sitemap.ts embutida não tem suporte de paginação.
Implemente um índice de sitemap com múltiplos arquivos de sitemap usando Route Handlers.
Cada arquivo de sitemap deve conter até 50.000 URLs por especificação do protocolo de sitemap.

Armadilha: `generateMetadata` é executado antes ou depois do componente da página?

generateMetadata é executado antes do componente da página.
Se ambos buscarem a mesma URL, o Next.js dedupica a solicitação.
No entanto, a função em si é executada separadamente da renderização da página.

Como você tiparia um objeto de dados estruturados JSON-LD usando `schema-dts`?

import type { WithContext, Article } from "schema-dts";
 
const jsonLd: WithContext<Article> = {
  "@context": "https://schema.org",
  "@type": "Article",
  headline: post.title,
  datePublished: post.createdAt.toISOString(),
};

schema-dts fornece tipos TypeScript para todos os tipos do Schema.org.

Relacionado

Internacionalização - hreflang e metadados específicos de localidade
Implantação - garantindo que os metadados funcionem em produção
Route Handlers de API - rotas dinâmicas de imagem OG
Documentação de Metadados do Next.js

// app/layout.tsx
import type { Metadata } from "next";
 
export const metadata: Metadata = {
  title: {
    default: "Meu App",
    template: "%s | Meu App",
  },
  description: "Uma aplicação web moderna construída com Next.js",
  metadataBase: new URL("https://myapp.com"),
  openGraph: {
    type: "website",
    locale: "pt_BR",
    siteName: "Meu App",
  },
  twitter: {
    card: "summary_large_image",
    creator: "@myapp",
  },
  robots: {
    index: true,
    follow: true,
  },
};
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="pt-BR">
      <body>{children}</body>
    </html>
  );
}

Metadados Dinâmicos com generateMetadata

// app/posts/[slug]/page.tsx
import type { Metadata, ResolvingMetadata } from "next";
import { notFound } from "next/navigation";
 
type Props = {
  params: Promise<{ slug: string }>;
};
 
export async function generateMetadata(
  { params }: Props,
  parent: ResolvingMetadata
): Promise<Metadata> {
  const { slug } = await params;
  const post = await db.post.findUnique({ where: { slug } });
 
  if (!post) {
    return {};
  }
 
  const parentMetadata = await parent;
  const previousImages = parentMetadata.openGraph?.images ?? [];
 
  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      title: post.title,
      description: post.excerpt,
      type: "article",
      publishedTime: post.createdAt.toISOString(),
      authors: [post.author.name],
      images: [
        {
          url: `/api/og?title=${encodeURIComponent(post.title)}`,
          width: 1200,
          height: 630,
          alt: post.title,
        },
        ...previousImages,
      ],
    },
    twitter: {
      card: "summary_large_image",
      title: post.title,
      description: post.excerpt,
    },
  };
}
 
export default async function PostPage({ params }: Props) {
  const { slug } = await params;
  const post = await db.post.findUnique({ where: { slug } });
 
  if (!post) notFound();
 
  return <article>{post.content}</article>;
}

Geração de Sitemap

// app/sitemap.ts
import type { MetadataRoute } from "next";
 
export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
  const posts = await db.post.findMany({
    select: { slug: true, updatedAt: true },
    orderBy: { updatedAt: "desc" },
  });
 
  const postEntries = posts.map((post) => ({
    url: `https://myapp.com/posts/${post.slug}`,
    lastModified: post.updatedAt,
    changeFrequency: "weekly" as const,
    priority: 0.8,
  }));
 
  const staticPages = [
    {
      url: "https://myapp.com",
      lastModified: new Date(),
      changeFrequency: "daily" as const,
      priority: 1.0,
    },
    {
      url: "https://myapp.com/about",
      lastModified: new Date(),
      changeFrequency: "monthly" as const,
      priority: 0.5,
    },
  ];
 
  return [...staticPages, ...postEntries];
}

Robots.txt

// app/robots.ts
import type { MetadataRoute } from "next";
 
export default function robots(): MetadataRoute.Robots {
  return {
    rules: [
      {
        userAgent: "*",
        allow: "/",
        disallow: ["/api/", "/admin/", "/dashboard/"],
      },
    ],
    sitemap: "https://myapp.com/sitemap.xml",
  };
}

Dados Estruturados JSON-LD

// app/posts/[slug]/page.tsx
import type { WithContext, Article } from "schema-dts";
 
function JsonLd({ data }: { data: WithContext<Article> }) {
  return (
    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }}
    />
  );
}
 
export default async function PostPage({ params }: Props) {
  const { slug } = await params;
  const post = await db.post.findUnique({ where: { slug } });
 
  if (!post) notFound();
 
  const jsonLd: WithContext<Article> = {
    "@context": "https://schema.org",
    "@type": "Article",
    headline: post.title,
    description: post.excerpt,
    datePublished: post.createdAt.toISOString(),
    dateModified: post.updatedAt.toISOString(),
    author: {
      "@type": "Person",
      name: post.author.name,
    },
  };
 
  return (
    <>
      <JsonLd data={jsonLd} />
      <article>{post.content}</article>
    </>
  );
}

Imagem OG Dinâmica

// app/api/og/route.tsx
import { ImageResponse } from "next/og";
import { NextRequest } from "next/server";
 
export const runtime = "edge";
 
export async function GET(request: NextRequest) {
  const title = request.nextUrl.searchParams.get("title") ?? "Meu App";
 
  return new ImageResponse(
    (
      <div
        style={{
          fontSize: 60,
          color: "white",
          background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
          width: "100%",
          height: "100%",
          display: "flex",
          alignItems: "center",
          justifyContent: "center",
          padding: 60,
          textAlign: "center",
        }}
      >
        {title}
      </div>
    ),
    {
      width: 1200,
      height: 630,
    }
  );
}

Análise Detalhada

Como Funciona

A Metadata API é a forma principal de definir tags <head> no App Router. Exporte um objeto metadata ou uma função generateMetadata de page.tsx ou layout.tsx.
Metadados se mesclam na árvore de componentes. Metadados filhos substituem metadados pais. O padrão title.template no layout raiz ("%s | Meu App") é aplicado aos títulos das páginas filhas.
generateMetadata recebe metadados pais resolvidos através do segundo argumento. Isso permite estender imagens Open Graph pais ou outros valores herdados.
sitemap.ts e robots.ts são convenções de arquivo especiais. O Next.js os serve em /sitemap.xml e /robots.txt automaticamente.
metadataBase define a URL base para todas as URLs de metadados relativas (imagens Open Graph, URLs canônicas). Sempre defina-o no layout raiz.
ImageResponse de next/og gera imagens Open Graph dinâmicas usando JSX na edge. Ele usa Satori internamente, que suporta um subconjunto de CSS (apenas flexbox, sem grid).

Variações

Múltiplos Sitemaps (Sites Grandes):

// app/sitemap/[id]/route.ts
import { NextRequest } from "next/server";
 
export async function GET(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const page = parseInt(id, 10);
  const perPage = 50000;
 
  const posts = await db.post.findMany({
    skip: page * perPage,
    take: perPage,
    select: { slug: true, updatedAt: true },
  });
 
  const xml = `<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  ${posts.map((post) => `
  <url>
    <loc>https://myapp.com/posts/${post.slug}</loc>
    <lastmod>${post.updatedAt.toISOString()}</lastmod>
  </url>`).join("")}
</urlset>`;
 
  return new Response(xml, {
    headers: { "Content-Type": "application/xml" },
  });
}

URLs Canônicas:

export const metadata: Metadata = {
  alternates: {
    canonical: "/posts/my-post",
    languages: {
      "en-US": "/en/posts/my-post",
      "de-DE": "/de/posts/my-post",
    },
  },
};

Notas de TypeScript

Importe Metadata e ResolvingMetadata de "next" para inferência de tipo completa.
MetadataRoute.Sitemap é um array de objetos com url, lastModified, changeFrequency e priority.
Use o pacote schema-dts para dados estruturados JSON-LD tipados.
Os parâmetros de generateMetadata são assíncronos no Next.js 15+ (mesmo padrão Promise<{ slug: string }> das páginas).

Armadilhas

generateMetadata é executado antes do componente da página. Sua busca de dados é dedupicada com a busca da página se a mesma URL for solicitada, mas a função em si é executada separadamente.
metadataBase deve ser uma URL absoluta. URLs relativas em imagens Open Graph quebrarão sem ele.
Client Components não podem exportar metadados. O objeto metadata e a função generateMetadata só funcionam em Server Components (page.tsx e layout.tsx).
ImageResponse suporta apenas flexbox. CSS Grid, position: absolute (com exceções) e muitas propriedades CSS não são suportadas pelo Satori.
Arquivos de sitemap devem retornar todas as URLs. Não há paginação embutida. Para sites com mais de 50.000 URLs, implemente um índice de sitemap com múltiplos arquivos de sitemap manualmente.
title.template se aplica apenas a páginas filhas, não à página onde é definido. A própria página usa title.default.

Alternativas

Abordagem	Prós	Contras
Metadata API (embutida)	Type-safe, automática, co-localizada	Não pode ser usada em Client Components
Pacote `next-seo`	API familiar da era Pages Router	Redundante com a Metadata API embutida
Tags `<head>` manuais	Controle total	Sem segurança de tipo, fácil de esquecer tags
`schema-dts` para JSON-LD	Dados estruturados tipados	Dependência extra
Pacote `next-sitemap`	Geração automática, suporte ISR	Dependência extra, sobrecarga de configuração

FAQs

Qual a diferença entre a exportação `metadata` e `generateMetadata`?

metadata é um objeto estático para páginas com metadados fixos (por exemplo, a página inicial).
generateMetadata é uma função assíncrona para páginas onde os metadados dependem de dados dinâmicos (por exemplo, um post de blog).
Ambos são exportados de page.tsx ou layout.tsx e são apenas para Server Components.

Como funciona a mesclagem de metadados na árvore de componentes?

Metadados filhos substituem metadados pais para os mesmos campos.
O title.template no layout raiz (por exemplo, "%s | Meu App") é aplicado aos títulos das páginas filhas.
title.template se aplica apenas a páginas filhas, não à página onde é definido.

O que é `metadataBase` e por que é necessário?

metadataBase define a URL base para todas as URLs de metadados relativas (imagens OG, URLs canônicas).
Sem ele, URLs relativas em tags Open Graph quebrarão.
Defina-o para sua URL de produção no layout raiz: metadataBase: new URL("https://myapp.com").

Como funcionam `sitemap.ts` e `robots.ts` como convenções de arquivo?

Exportar uma função padrão de app/sitemap.ts a serve automaticamente em /sitemap.xml.
Exportar uma função padrão de app/robots.ts a serve automaticamente em /robots.txt.
Ambos podem ser assíncronos e buscar dados de um banco de dados.

Armadilha: Client Components podem exportar `metadata` ou `generateMetadata`?

Não. A Metadata API só funciona em Server Components.
metadata e generateMetadata devem ser exportados de page.tsx ou layout.tsx sem a diretiva "use client".

Quais limitações de CSS o `ImageResponse` (Satori) tem para imagens OG dinâmicas?

Apenas o layout flexbox é suportado; CSS Grid não funciona.
position: absolute tem suporte limitado.
Muitas propriedades CSS não são suportadas; mantenha os estilos das imagens OG simples.

Como adicionar dados estruturados JSON-LD a uma página?

<script
  type="application/ld+json"
  dangerouslySetInnerHTML={{
    __html: JSON.stringify(jsonLdObject),
  }}
/>

Renderize uma tag <script type="application/ld+json"> no componente da página.
Use o pacote schema-dts para objetos JSON-LD tipados.

Como tipar os parâmetros de `generateMetadata` em TypeScript para Next.js 15+?

import type { Metadata, ResolvingMetadata } from "next";
 
type Props = {
  params: Promise<{ slug: string }>;
};
 
export async function generateMetadata(
  { params }: Props,
  parent: ResolvingMetadata
): Promise<Metadata> {
  const { slug } = await params;
  // ...
}

params é uma Promise no Next.js 15+ e deve ser aguardada.

O que é `ResolvingMetadata` e como usá-lo?

É o segundo argumento para generateMetadata, fornecendo metadados pais resolvidos.
Use-o para estender imagens Open Graph pais: const prev = (await parent).openGraph?.images ?? [].
Isso permite que páginas filhas herdem e aumentem os metadados pais.

Como lidar com sitemaps para sites com mais de 50.000 URLs?

A convenção sitemap.ts embutida não tem suporte de paginação.
Implemente um índice de sitemap com múltiplos arquivos de sitemap usando Route Handlers.
Cada arquivo de sitemap deve conter até 50.000 URLs por especificação do protocolo de sitemap.

Armadilha: `generateMetadata` é executado antes ou depois do componente da página?

generateMetadata é executado antes do componente da página.
Se ambos buscarem a mesma URL, o Next.js dedupica a solicitação.
No entanto, a função em si é executada separadamente da renderização da página.

Como você tiparia um objeto de dados estruturados JSON-LD usando `schema-dts`?

import type { WithContext, Article } from "schema-dts";
 
const jsonLd: WithContext<Article> = {
  "@context": "https://schema.org",
  "@type": "Article",
  headline: post.title,
  datePublished: post.createdAt.toISOString(),
};

schema-dts fornece tipos TypeScript para todos os tipos do Schema.org.

Relacionado

Internacionalização - hreflang e metadados específicos de localidade
Implantação - garantindo que os metadados funcionem em produção
Route Handlers de API - rotas dinâmicas de imagem OG
Documentação de Metadados do Next.js

SEO e Metadados

Receita

Exemplo de Trabalho

Metadados Estáticos

Metadados Dinâmicos com generateMetadata

Geração de Sitemap

Robots.txt

Dados Estruturados JSON-LD

Imagem OG Dinâmica

Análise Detalhada

Como Funciona

Variações

Notas de TypeScript

Armadilhas

Alternativas

FAQs

Relacionado

SEO e Metadados

Receita

Exemplo de Trabalho

Metadados Estáticos

Metadados Dinâmicos com generateMetadata

Geração de Sitemap

Robots.txt

Dados Estruturados JSON-LD

Imagem OG Dinâmica

Análise Detalhada

Como Funciona

Variações

Notas de TypeScript

Armadilhas

Alternativas

FAQs

Relacionado

SEO e Metadados

Buscar na documentação

SEO e Metadados