homaroma/.agents/skills/nextjs-seo-architect/references/seo-build-checklist.md

Next.js SEO And Build Checklist

Use this checklist for audits, implementation review, and final handoff. Apply only the sections relevant to the task.

Discovery

• Confirm Next.js version from package.json and lockfile.
• Confirm router type: App Router, Pages Router, or hybrid.
• Confirm package manager and scripts.
• Review next.config.*.
• Review deployment target if visible in repo.
• Locate route definitions and content/data source.
• Locate existing SEO helpers, metadata builders, schema builders, sitemap, robots, redirects, and middleware.

Metadata

• Unique title per indexable page.
• Unique meta description per indexable page.
• Canonical URL is absolute, normalized, and self-referencing.
• Root title template is intentional.
• Open Graph title, description, URL, type, image, and site name are correct.
• Twitter card values are correct.
• Robots directives match index policy.
• Metadata does not depend on browser-only state.
• Dynamic metadata handles missing records with notFound() or a clear fallback policy.

Structured Data

• JSON-LD type matches visible page content.
• Entity IDs and URLs match canonical URLs.
• Required fields are present.
• Recommended fields are present when source data exists.
• Product price, availability, review, SKU, brand, and image data match visible product content.
• Article author, date, modified date, headline, image, and publisher match visible article content.
• Breadcrumb JSON-LD matches visible or implied navigation hierarchy.
• JSON serialization is safe.

Crawl Paths

• Main navigation uses crawlable links.
• Important listing/detail pages are reachable without form-only or script-only flows.
• Pagination and filters have an intentional index/canonical/noindex policy.
• Empty states do not create thin indexable pages unless intended.
• 404, notFound(), redirects, and unpublished states behave correctly.

Sitemap

• Uses canonical production origin.
• Includes only indexable canonical URLs.
• Excludes private, draft, duplicate, auth, cart, checkout, account, search-result, and noindex routes.
• Includes localized alternates when supported by source data.
• Uses realistic lastModified.
• Handles large URL sets with sitemap splitting when needed.
• Is referenced from robots.

Robots

• Allows intended public pages.
• Disallows private or duplicate areas.
• Does not block static assets needed for rendering.
• References the sitemap.
• Does not accidentally block the whole site in production.

International SEO

• Locale URL strategy is consistent.
• Canonical points to the locale-specific URL.
• hreflang alternates include only real translated equivalents.
• x-default is intentional.
• Localized metadata is not copied blindly from another language.
• Slugs, breadcrumbs, schema, and Open Graph data respect locale.

Rendering

• Crawl-critical content is present in server-rendered HTML.
• Client Components are limited to interactive parts.
• Route rendering mode is intentional: static, ISR, dynamic, or client-only.
• generateStaticParams covers expected static routes.
• Cache and revalidation behavior match content freshness.
• Accidental dynamic rendering has been checked.

Performance

• LCP image is optimized and sized.
• Non-critical images are lazy-loaded.
• Fonts are optimized and do not cause avoidable layout shift.
• Third-party scripts use the correct strategy.
• Bundle size impact is checked for new libraries.
• Layout shift risks are checked for banners, hero media, product grids, and dynamic content.

Accessibility Signals

• One clear h1 per primary page.
• Heading hierarchy is meaningful.
• Images have useful alt text or empty alt for decorative images.
• Links have descriptive accessible names.
• Product/article/category content is readable without visual-only cues.

Build Verification

• Run typecheck.
• Run lint.
• Run focused tests if available.
• Run production build.
• Inspect build output for rendering mode changes.
• Check warnings related to metadata, dynamic server usage, image config, middleware, redirects, or unsupported runtime.

Handoff

• Summarize changed SEO behavior.
• List affected routes and files.
• Include verification commands and results.
• Call out unresolved source-data, CMS, backend, deployment, or business-policy decisions.
• Identify the next owner when decisions are outside frontend/SEO implementation.