# SEO Metadata > Apply Next.js Metadata API per route — title template, og:image, generateMetadata for dynamic pages, JSON-LD structured data, robots, sitemap, canonical, hreflang. Use when adding a new route, when search visibility drops, when rich results are needed, or before shipping. Not for choosing a route's render mode (use render-strategy-decision); align generateMetadata with that route caching choice. - Skill: `jaykim88/seo-metadata` (Agent Skill) - Install (CLI): `npx skillmds@latest add jaykim88/seo-metadata` - Raw SKILL.md: https://api.skillmd.com/api/skills/jaykim88/seo-metadata/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Marketing & Growth - License: MIT - Author: JayKim88 (https://skillmd.com/u/jaykim88) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/jaykim88/seo-metadata --- # SEO and Metadata ## Purpose Every public route is correctly indexable, shows good social previews, and signals canonical URLs to crawlers. Bad metadata costs traffic — and is invisible until traffic data shows the loss. **Universal fields, platform-bound Procedure** — the metadata *fields* (title, description, og:*, robots, canonical, sitemap, robots.txt) are HTML/HTTP standards. But the Procedure below is written concretely against the **Next.js Metadata API** (`export const metadata`, `generateMetadata`, `sitemap.ts`); the Other stacks section maps the equivalent API per framework (Nuxt `useSeoMeta`, SvelteKit ``, Angular `Meta`/`Title`). ## Procedure 0. **Set a base URL** (Next.js: `metadataBase` in root layout — required for relative URLs) - Without it, relative OG image paths cause build errors: ```ts // app/layout.tsx export const metadata = { metadataBase: new URL('https://yoursite.com'), // ... }; ``` - With `metadataBase` set, `openGraph.images: '/og.png'` resolves to absolute URLs automatically 1. **Static pages: use `export const metadata`** - Direct object, no function overhead - Define `title`, `description`, `openGraph`, `twitter`, `robots` - Quality: unique `title` (~50–60 chars) and `description` (~150–160 chars) per route — duplicate or template-only titles across pages are a common ranking loss 2. **Dynamic pages: `generateMetadata` function** - Async — can fetch the page data - Rely on fetch memoization — the same fetch in `generateMetadata` and the page render is deduplicated automatically - Don't wrap a static page in `generateMetadata` (unnecessary overhead) 3. **Define title template at the root layout** ```ts export const metadata = { title: { template: '%s | App Name', default: 'App Name' } } ``` - Child routes set `title: 'About'` → renders `About | App Name` - **`title.default` is required when `title.template` is set** — missing it will error at build time. The `default` covers routes that don't set their own title. 4. **Open Graph (social previews)** - `og:title`, `og:description`, `og:image` per route - Image: 1200x630, < 1MB, hosted at a stable URL - Complete the set: `og:type`, `og:url`, `og:site_name`, image `alt`, and `twitter.card: 'summary_large_image'` — partial OG tags render poor previews - File-based: place `opengraph-image.png` next to `page.tsx` - Test the rendered preview (Twitter card validator, LinkedIn post inspector, OpenGraph.xyz) - **Streaming metadata note (Next.js 15.2+)**: metadata may stream into `` for JS-capable bots, but HTML-limited bots (e.g., `facebookexternalhit`) still block on `generateMetadata` — keep dynamic metadata generation fast. Rely on Next.js fetch memoization to dedupe data between `generateMetadata` and the page render. 5. **Block non-public pages from indexing** - Auth pages, admin, settings, search-result pages - `metadata = { robots: { index: false, follow: false } }` - **`robots.txt` Disallow ≠ noindex**: Disallow blocks crawling, but a blocked URL can still be indexed (without content). To remove a page from the index use a `noindex` meta — not `Disallow` - ⚠ **Guard against a site-wide `noindex` / `Disallow: /` reaching production** (a staging config leaking to prod silently de-indexes everything) — verify prod in step 8 6. **Canonical URLs and locale alternates** - Set a self-referencing canonical on every indexable page; for pages reachable by multiple URLs (query-string variants), point them all to one canonical - `metadata = { alternates: { canonical: '/the-canonical-path' } }` - Don't canonicalize to a `noindex`/redirected URL, and don't canonical paginated pages back to page 1 (each page is its own canonical) - **Multi-locale**: declare `alternates.languages` (hreflang) so crawlers serve the right locale (coordinate with `i18n-localization`) 7. **Generate `sitemap.ts` and `robots.ts`** - App Router supports these as conventional files in the app root - `sitemap.ts` exports a function returning all public URLs - `robots.ts` declares allow/disallow rules - Include only indexable, canonical, 200-status URLs (never noindex/redirected ones); add `lastModified`; for > 50k URLs use a sitemap index 7b. **Add structured data (JSON-LD) for rich results** - Inject a `