Kit de SEO
Metadata, hreflang, JSON-LD, sitemaps, robots.txt, llms.txt e RSS prontos para o blog a partir dos posts do Postream.
O pacote @postream/seo traz o cliente da API pública e o kit de SEO para blogs em Next.js: metadata com canonical e hreflang (x-default no idioma padrão), JSON-LD num único @graph por página, sitemaps por idioma com índice, robots.txt liberando os crawlers de busca e de IA, llms.txt, índice com âncoras, FAQ em <details>, posts relacionados e RSS. Funções puras, sem dependência de runtime; os retornos encaixam nos tipos Metadata e MetadataRoute do Next.
pnpm add @postream/seoConfigurar
Só no servidor, sem NEXT_PUBLIC_, com a chave secreta:
POSTREAM_API_URL=https://api.postream.blog/public/v1
POSTREAM_SITE_ID=7c0e...
POSTREAM_API_KEY=sk_...Com siteId, o cliente usa a rota por site (cache na borda, purgado quando o post muda) e manda a query das listagens na forma canônica. postPath diz onde cada versão mora no blog; o pacote não supõe nenhuma estrutura de URL.
import { createPostreamClient, organizationFromSite, type GraphConfig } from "@postream/seo";
export const postream = createPostreamClient({
apiUrl: process.env.POSTREAM_API_URL!,
siteId: process.env.POSTREAM_SITE_ID!,
apiKey: process.env.POSTREAM_API_KEY!,
// Revalida a cada 5 minutos (ISR) ou na hora, pela tag, quando chega um webhook.
init: { next: { revalidate: 300, tags: ["postream"] } },
});
export const site = await postream.getSite();
export const seo: GraphConfig = {
siteUrl: site.url,
defaultLocale: site.xDefaultLocale,
postPath: ({ locale, slug }) => `/${locale}/blog/${slug}`,
// Nome, descrição e perfis vêm do painel; o tamanho do logo é seu.
organization: organizationFromSite(site, { width: 512, height: 512 }),
// Para posts sem imagem de tamanho conhecido.
defaultImage: { url: "/og.png", width: 1200, height: 630 },
};Página do post
import type { Metadata } from "next";
import { notFound, permanentRedirect } from "next/navigation";
import { postJsonLd, postMetadata, postParts, postSummary, postUrl, serializeJsonLd } from "@postream/seo";
import { postream, seo } from "@/lib/postream";
type Props = { params: Promise<{ locale: string; slug: string }> };
export async function generateMetadata({ params }: Props): Promise<Metadata> {
const { locale, slug } = await params;
const post = await postream.getPost(slug, { locale });
return post ? postMetadata(post, seo) : {};
}
export default async function BlogPost({ params }: Props) {
const { locale, slug } = await params;
const post = await postream.getPost(slug, { locale });
if (!post) notFound();
// A API seguiu o 301 de um slug antigo: manda o visitante para a URL nova.
if (post.slug !== slug) permanentRedirect(postUrl(seo, post));
const { bodyHtml, faq } = postParts(post);
return (
<article>
<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: serializeJsonLd(postJsonLd(post, seo)) }} />
<h1>{post.title}</h1>
<p>{postSummary(post)}</p>
<div dangerouslySetInnerHTML={{ __html: bodyHtml }} />
{faq.map((q) => (
<details key={q.id} id={q.id}>
<summary>{q.question}</summary>
<p>{q.answer}</p>
</details>
))}
</article>
);
}O grafo traz Organization, WebSite, WebPage, BreadcrumbList, Person, BlogPosting e, quando o post tiver, FAQPage e HowTo. serializeJsonLd escapa <, > e &: texto do post não fecha a tag <script>. Nos testes do blog, validateJsonLdGraph(postJsonLd(post, seo)) devolve [] quando o grafo está íntegro.
Sitemaps, robots.txt e llms.txt
// app/sitemap.ts
import { postsSitemap } from "@postream/seo";
import { postream, seo } from "@/lib/postream";
export default async function sitemap() {
return postsSitemap(await postream.listSitemap(), seo);
}
// app/robots.ts
import { robots } from "@postream/seo";
import { seo } from "@/lib/postream";
export default function robotsTxt() {
return robots(seo, { disallow: ["/api/"] });
}Para um sitemap por idioma com índice, use localeSitemaps, sitemapIndexXml e sitemapXml. O llms.txt sai de llmsTxt(await postream.listAllPosts(), seo, { categories: site.categories }). O lastmod e o dateModified vêm do updatedAt da API, que só muda com o conteúdo.
Outros helpers
postsRss (RSS 2.0), relatedPosts (pilar ↔ satélites), tableOfContents, authorProfile, siteJsonLd (home e listagens), postAlternates, languageAlternates e absoluteUrl. O cliente também tem listPosts, listAllPosts, listAuthors, getAuthor e listCategories. Erros da API saem como PostreamApiError com status e code; getPost e getAuthor devolvem null no 404.
Para medir leitura e engajamento das mesmas páginas, veja Analytics.