SEO

Metadata, JSON-LD, sitemaps, robots.txt, feeds and responsive images, each rule an assert* that throws a coded SeoError naming the route file and the edit. Package @ultimat3/seo (tier 1) — the full reference is packages/seo/README.md. Route metadata itself is declared on defineRoute({ meta }) (Routes and render modes).

export const config = defineRoute({
  render: 'isr',
  meta: ({ post }) => ({
    title: post.title,
    titleTemplate: '%s — Ultimate',
    description: post.excerpt,
    og: { type: 'article', image: post.cover, publishedTime: post.publishedAt },
    ld: [ld.Article({ headline: post.title, datePublished: post.publishedAt, author: post.author })],
  }),
});

What the rules refuse

x verify's seo step runs validateMeta over every site/ route: missing, duplicate and over-long meta fail the gate. Canonical checks are skipped there, because an app declares no base URL; JSON-LD, sitemaps and robots are enforced where they are built — each builder throws. Performance budgets are not here: they are the budgets step and X_BUDGET_EXCEEDED.

Head links

meta.links puts <link> tags in <head> — a font preload, a preconnect, a feed — typed, in declaration order, for SSR and prerender alike. canonical and hreflang keep their own fields, and the surface stylesheet is the renderer's, so neither rel is spellable here.

export const config = defineRoute({
  render: 'static',
  meta: () => ({
    title: 'Acme',
    description: 'Notificaciones electrónicas con constancia de entrega',
    links: [
      {
        rel: 'preload',
        href: asset('assets/fonts/inter-var.woff2'),
        as: 'font',
        type: 'font/woff2',
        crossorigin: 'anonymous',
      },
      { rel: 'alternate', href: '/feed.xml', type: 'application/rss+xml' },
    ],
  }),
});

Fields: rel, href, as, type, crossorigin, media. Two links of one rel are two tags: a link's href is part of its identity when the head is deduped.

The social card

A document that may not be indexed carries no card — no og:*, no article:*, no twitter:* tag, declared or derived — unless the route declares socialCard: true. meta.robots: { index: false } says so, and so does a 4xx or 5xx, which @ultimat3/render marks noindex by construction. A document that may be indexed carries its card whatever the field says. As of 2026-10.

meta.socialCard: true is the route's own opt-in, and the only one. With it, a noindex document carries the card exactly as an indexable one does: declared values win, and the derived ones come with it — og:type, og:title and og:description from the page's own title and description, og:url from the canonical, og:locale, and the twitter:card default. The robots directives never change: renderMeta() still answers <meta name="robots" content="noindex,follow">, and the route stays noindex.

import { defineRoute } from '@ultimat3/render';

export const config = defineRoute({
  render: 'isr',
  revalidate: { ttl: '5m' },
  offline: 'network-only',
  meta: () => ({
    title: 'Pricing',
    description: 'What the plan costs.',
    robots: { index: false },
    socialCard: true,
  }),
});

A card the build photographs: og.capture

og: { capture: '/og/home' } names a site/ page — one you write, laid out at exactly 1200 x 630, robots: { index: false } — and x build --target static photographs it into /_og/og/home.png and stamps og:image, og:image:width and og:image:height on every exported document that declares it. image and capture are one or the other; both together is a type error. As of 2026-11.

import { defineRoute } from '@ultimat3/render';

export const config = defineRoute({
  render: 'static',
  offline: 'network-only',
  meta: () => ({
    title: 'Postly',
    description: 'A team blog that behaves itself.',
    og: { capture: '/og/home' },
  }),
});

A card for a ROW published at runtime is the app's job, not the build's: scrape() over the row's card page, page.screenshot(), disk.put(), then og: { image } with the stored object's URL — Scraping.

The pieces

Every X_SEO_* and image code is in Error codes.

robots.txt and sitemap.xml

One answer, served two ways. siteSeo() from @ultimat3/cli builds both from the route table. It takes the public site/ routes (no policy) and expands a dynamic route through its prerender().

Production robots.txt rules come from app.config.ts: seo.robots.disallow (every crawler, in every group) and seo.robots.groups (per User-agent) — Configuration. A crawler obeys only the group naming it most specifically, so a group for GPTBot replaces *'s rules for it. Any other environment emits Disallow: / alone, whatever either says.

What is left out

A page's own lastmod and locales

prerender() answers a bare string, a params object, or an entry — the three mix freely:

import { defineRoute } from '@ultimat3/render';

declare const posts: {
  published(): Promise<readonly { slug: string; updatedAt: Date; englishReviewed: boolean }[]>;
};

export const config = defineRoute({
  render: 'isr',
  revalidate: { ttl: '10m' },
  offline: 'network-only',
  prerender: async () =>
    (await posts.published()).map((post) => ({
      params: { slug: post.slug },
      lastmod: post.updatedAt, // a Date, or ISO 8601 with a zone
      locales: post.englishReviewed ? ['es-co', 'en'] : ['es-co'],
    })),
  meta: ({ params }) => ({ title: params['slug'] ?? '', description: 'A note from the blog.' }),
});

A route with no params may answer prerender() too — () => [{ params: {}, lastmod, locales }] — which is how a page with a load (a blog index whose date is its newest post's) says either.

A key that is none of the three (lastMod) is X_PRERENDER_FAILED. The static export still lists only the pages it emitted; it asks prerender() again for what each says of itself.

The <head> is separate: a page's hreflang tags come from meta.alternates, or from every routed locale when it declares none. A page listed in one locale declares its own: alternates: [{ hreflang: 'es-CO', href: url }].

Sections: an index by configuration

import { defineConfig } from '@ultimat3/core';

export const config = defineConfig({
  name: 'acme',
  seo: {
    sitemap: {
      pageSize: 1000,
      sections: [
        { name: 'blog', match: '/blog/**' },
        { name: 'ciudades', match: ['/juzgados/**', '/ciudades/*'] },
      ],
    },
  },
});

/sitemap.xml becomes a <sitemapindex>; every listed page goes to /sitemaps/<name>-<n>.xml.

With no sections the output is byte-for-byte what it was: one urlset at /sitemap.xml, and past a cap (50,000 URLs, or 50 MB) the index with parts /sitemaps/1.xml, /sitemaps/2.xml, … (SITEMAP_PARTS_DIR). A part the index does not name is a 404, no-store. As of 2026-10.

llms.txt

As of 2026-11-06. A third file of the same answer, on by default like the sitemap. /llms.txt lists the indexable site/ pages a sitemap lists, by their meta title and description, in path order, under the home page's title and description:

# Postly

> Posts for teams.

- [Pricing](https://postly.example/pricing): Plans, per seat.

The repository's own llms.txt is a separate, hand-kept file and is not this.

Beyond site/, and <lastmod> (As of 22.10) — seo.sitemap in app.config.ts:

seo: { sitemap: { extra: ['/verificar', '/estado'], lastmod: 'git' } },

The scaffolded prerender.ts passes sitemap and root from loadSiteSettings(root); an app with its own prerender.ts adds sitemap: settings.sitemap, root to its siteSeo({ … }) call.

The parts of a split were /sitemap-N.xml once, which no running process could serve (Upgrading).