nextjs-metadata-seo-and-file-conventions

Next.js Metadata, SEO, and File Conventions

Use this skill when the task is mostly about search, sharing, metadata composition, or App Router file-convention outputs.

Scope

• static metadata exports and dynamic generateMetadata
• generateViewport
• metadata files like robots.txt, sitemap.xml, manifest.json, and icons
• Open Graph and Twitter image workflows
• canonical URLs and structured data placement
• choosing file conventions vs runtime functions

Routing cues

• generateMetadata, metadata objects, OG images, Twitter images, robots.txt, sitemap, manifest, icons, canonical URLs, or JSON-LD -> use this skill
• data loading and cache invalidation as the primary problem -> use nextjs-data-fetching-and-cache
• Route Handlers or mutation boundaries as the primary concern -> use nextjs-server-actions-and-route-handlers

Default path

1. Read references/metadata-and-file-conventions.md first.
2. Decide whether the output is static, request-aware, or generated from content state.
3. Prefer file conventions for stable framework-owned outputs.
4. Keep canonical URL logic and public URL assembly centralized.

When to deviate

• Use generateMetadata only when metadata actually depends on params, search params, or fetched content.
• Generate OG images at runtime only when static image assets are not enough.
• Move to the data-fetching skill when the hard part is content loading or cache ownership rather than metadata composition.
• Use a Route Handler only when the framework file convention does not own the output surface.

Quick example

import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'Docs',
  description: 'Product documentation',
}

Guardrails

• Prefer static metadata when values do not depend on request-time data.
• Use generateMetadata only when metadata genuinely depends on params, search params, or fetched content.
• Keep sitemap, robots, and canonical URLs derived from the same source of truth.
• Use metadata file conventions instead of hand-rolled endpoints when the framework already owns the surface.
• Treat OG-image generation as a public runtime surface with performance and cache implications.