Postream

Cargando el índice…

Documentación: Kit de SEO

Kit de SEO

Metadata, hreflang, JSON-LD, sitemaps, robots.txt, llms.txt y RSS listos para el blog a partir de los posts de Postream.

El paquete @postream/seo trae el cliente de la API pública y el kit de SEO para blogs en Next.js: metadata con canonical y hreflang (x-default en el idioma predeterminado), JSON-LD en un único @graph por página, sitemaps por idioma con índice, robots.txt que habilita los crawlers de búsqueda y de IA, llms.txt, índice con anclas, FAQ en <details>, posts relacionados y RSS. Funciones puras, sin dependencias de runtime; lo que devuelven encaja en los tipos Metadata y MetadataRoute de Next.

pnpm add @postream/seo

Configurar

Solo en el servidor, sin NEXT_PUBLIC_, con la clave secreta:

.env
POSTREAM_API_URL=https://api.postream.blog/public/v1
POSTREAM_SITE_ID=7c0e...
POSTREAM_API_KEY=sk_...

Con siteId, el cliente usa la ruta por sitio (caché en el borde, purgada cuando el post cambia) y envía la query de los listados en la forma canónica. postPath dice dónde vive cada versión en el blog; el paquete no supone ninguna estructura de URL.

lib/postream.ts
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 cada 5 minutos (ISR) o al instante, por la tag, cuando llega un 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}`,
  // Nombre, descripción y perfiles vienen del panel; el tamaño del logo lo defines tú.
  organization: organizationFromSite(site, { width: 512, height: 512 }),
  // Para posts sin imagen de tamaño conocido.
  defaultImage: { url: "/og.png", width: 1200, height: 630 },
};

Página del post

app/[locale]/blog/[slug]/page.tsx
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();
  // La API siguió el 301 de un slug antiguo: envía al visitante a la URL nueva.
  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>
  );
}

El grafo trae Organization, WebSite, WebPage, BreadcrumbList, Person, BlogPosting y, cuando el post los tiene, FAQPage y HowTo. serializeJsonLd escapa <, > y &: el texto del post no cierra la etiqueta <script>. En los tests del blog, validateJsonLdGraph(postJsonLd(post, seo)) devuelve [] cuando el grafo está íntegro.

Sitemaps, robots.txt y 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 un sitemap por idioma con índice, usa localeSitemaps, sitemapIndexXml y sitemapXml. El llms.txt sale de llmsTxt(await postream.listAllPosts(), seo, { categories: site.categories }). El lastmod y el dateModified vienen del updatedAt de la API, que solo cambia con el contenido.

Otros helpers

postsRss (RSS 2.0), relatedPosts (pilar ↔ satélites), tableOfContents, authorProfile, siteJsonLd (home y listados), postAlternates, languageAlternates y absoluteUrl. El cliente también tiene listPosts, listAllPosts, listAuthors, getAuthor y listCategories. Los errores de la API salen como PostreamApiError con status y code; getPost y getAuthor devuelven null en el 404.

Para medir lectura y engagement de las mismas páginas, mira Analítica.