next-heraldSEO, native. For the Next.js 16 App Router.

01 · The problem

SEO moved into Next itself.

The App Router moved SEO into Next itself (generateMetadata, sitemap.ts, robots.ts, opengraph-image). The popular packages come from the Pages Router era.

A Next.js 16 App Router–only SEO kit that returns native Metadata, MetadataRoute.Sitemap/Robots and ImageResponse objects, fills the gaps Next leaves, and ships herald check, a dependency-free CI crawler for technical SEO mistakes. It makes no ranking or AI-citation claims and no performance claims.

02 · How it works

Native objects in, a crawler to check what shipped.

Design principles

1. Native first. Return objects Next renders; never render our own <head> tags. ADR 0001
2. Zero dependencies. Only the next and react peers; the CLI uses Node built-ins. Enforced in CI. ADR 0002
3. Static by default. Never read headers or cookies, so pages stay in the Cache Components static shell. ADR 0006
4. Safe by default. JSON-LD is escaped; previews are noindex unless built for production. ADR 0004
5. Check what crawlers see. herald check reads served HTML, not Next internals. ADR 0008

03 · Features planned

Everything in the README, nothing more.

04 · Quick start planned API

From install to typed output.

// herald.config.ts
import { defineHerald } from 'next-herald/config';

export default defineHerald({
  siteUrl: 'https://example.com',
  siteName: 'Example',
  title: { default: 'Example', template: '%s · Example' },
  description: 'What Example does, in one sentence.',
});

// app/layout.tsx (excerpt)
import { createMetadata } from 'next-herald/metadata';
import herald from '@/herald.config';
export const metadata = createMetadata(herald);

// app/blog/[slug]/page.tsx
import { pageMetadata } from 'next-herald/metadata';
import { JsonLd, jsonLd } from 'next-herald/jsonld';
import herald from '@/herald.config';
import { getPost } from '@/lib/posts';

export async function generateMetadata({ params }: PageProps<'/blog/[slug]'>) {
  const { slug } = await params;
  const post = await getPost(slug);
  return pageMetadata(herald, { path: `/blog/${slug}`, title: post.title, description: post.excerpt, type: 'article' });
}

export default async function Page({ params }: PageProps<'/blog/[slug]'>) {
  const { slug } = await params;
  const post = await getPost(slug);
  return (
    <article>
      <JsonLd data={jsonLd.article({ headline: post.title, datePublished: post.date, author: { name: post.author } })} />
      <h1>{post.title}</h1>
    </article>
  );
}

// app/sitemap.ts
import { defineSitemap } from 'next-herald/sitemap';
import { routes } from '@/herald-routes.gen'; // written by `herald routes` (v0.2); v0.1: a hand-written list
import herald from '@/herald.config';
import { listSlugs } from '@/lib/posts';

export default defineSitemap(herald, {
  routes,
  params: { '/blog/[slug]': async () => (await listSlugs()).map((slug) => ({ slug })) }, // missing key = type error
});

// app/robots.ts
import { defineRobots } from 'next-herald/robots';
import herald from '@/herald.config';
export default defineRobots(herald, { rules: [{ userAgent: '*', disallow: ['/admin'] }] });

npx herald check --build --format github   # CI

Full walkthrough: Getting started · API reference · CLI

05 · Configuration

herald.config.ts reference

Abridged. Full reference in docs/configuration.md.

07 · Roadmap

Where it's going.

1. v0.1

   Core builders, ship fast: config, metadata builders, <JsonLd> + 7 types, basic sitemap/robots, CI with dependency budget

   next up
2. v0.2

   herald check core (titles, descriptions, canonicals, noindex, sitemap/robots, no-JS visibility, links, Lighthouse-equivalent basics, AI-crawler robots) + herald routes + entity graph

3. v0.3

   Large sites & i18n: sitemap index, news, hreflang, next-tongue adapter, static export, accurate lastmod

4. v0.4

   OG templates, JSON-LD, OG, citation-friendly structure and entity rules, more schema types, SARIF

5. v0.5

   herald init, herald indexnow, verified migration guides, published size/perf report, AI referral docs; experimental markdown alternates and llms.txt

6. v0.9

   Beta: API and rule-ID freeze

7. v1.0

   Stable, semver guarantees

8. post-1.0

   next-seo / next-sitemap codemods

Scope freeze: no new features before v0.1 ships. Acceptance criteria in ROADMAP.md.