Next.js SEO & Metadata Foundation

A checklist + code for making a Next.js (App Router) site indexable, shareable, and branded. Apply all of it to a new site; cherry-pick for an existing one.

0. Single source of truth for the site URL

Everything below depends on one absolute origin, with no trailing slash. A trailing slash silently produces https://site.com//canonical and breaks SEO.

// src/lib/site.ts
export const siteUrl =
  process.env.NEXT_PUBLIC_SITE_URL?.replace(/\/+$/, "") ?? "https://example.com";

Set NEXT_PUBLIC_SITE_URL in the host env (Vercel etc.). It bakes in at build time — you must redeploy after changing it.

1. Root metadata (app/layout.tsx)

import type { Metadata } from "next";
import { siteUrl } from "@/lib/site";

const title = "Brand — one-line value prop";

export const metadata: Metadata = {
  metadataBase: new URL(siteUrl),            // makes OG/canonical URLs absolute
  title: { default: title, template: "%s | Brand" },
  description: "150–160 char description.",
  alternates: { canonical: "/" },
  openGraph: { title, description: "…", url: "/", siteName: "Brand", type: "website" },
  twitter: { card: "summary_large_image", title, description: "…" },
  robots: { index: true, follow: true },
};

Per-route pages export their own metadata with a route-specific alternates.canonical: "/path".

2. Open Graph image (app/opengraph-image.tsx)

Generated at build time — no design tool needed. Gotcha: Satori (the renderer) requires an explicit display on any element with more than one child, and does not support <br/> — use flex rows/columns instead.

import { ImageResponse } from "next/og";

export const alt = "Brand — value prop";
export const size = { width: 1200, height: 630 };
export const contentType = "image/png";

export default function OpengraphImage() {
  return new ImageResponse(
    (
      <div style={{ width: "100%", height: "100%", display: "flex", flexDirection: "column",
        justifyContent: "space-between", padding: 72, background: "#111827", color: "#fff",
        fontFamily: "sans-serif" }}>
        <div style={{ display: "flex", fontSize: 28, fontWeight: 700 }}>Brand</div>
        <div style={{ display: "flex", fontSize: 60, fontWeight: 700, lineHeight: 1.1 }}>
          The headline, in one or two lines.
        </div>
      </div>
    ),
    size,
  );
}

3. robots (app/robots.ts) and sitemap (app/sitemap.ts)

// app/robots.ts
import type { MetadataRoute } from "next";
import { siteUrl } from "@/lib/site";
export default function robots(): MetadataRoute.Robots {
  return { rules: { userAgent: "*", allow: "/", disallow: "/api/" },
    sitemap: `${siteUrl}/sitemap.xml`, host: siteUrl };
}

// app/sitemap.ts — generate entries from your route/content registry so it can't drift
import type { MetadataRoute } from "next";
import { siteUrl } from "@/lib/site";
export default function sitemap(): MetadataRoute.Sitemap {
  return [{ url: siteUrl, lastModified: new Date(), changeFrequency: "monthly", priority: 1 }];
}

4. JSON-LD structured data

Add a <script type="application/ld+json"> in layout.tsx. The content is static and authored in-repo, so dangerouslySetInnerHTML is safe here. Pick the right @type: Person + ProfessionalService for a consultant, SoftwareApplication for a tool/app, Organization for a company, FAQPage if you render an FAQ.

<script type="application/ld+json"
  dangerouslySetInnerHTML={{ __html: JSON.stringify({
    "@context": "https://schema.org", "@type": "SoftwareApplication",
    name: "Brand", url: siteUrl, applicationCategory: "DeveloperApplication",
  }) }} />

5. App shell — never ship the stock Next error screens

• app/not-found.tsx — branded 404 with a link home.
• app/error.tsx — "use client", logs the error, offers a reset() button.
• app/loading.tsx on routes that do real client work.

Verification (do this on the deployed URL, not just locally)

curl -s https://SITE/robots.txt          # Host + Sitemap must be the real origin, no //
curl -s https://SITE/sitemap.xml         # <loc> must be the real origin, no //
curl -sI https://SITE/opengraph-image    # 200, content-type image/png
curl -s https://SITE/ | grep -i canonical  # canonical must be the origin, no trailing //

The mistakes this prevents (seen repeatedly)

• No og:image → every LinkedIn/Slack share is a blank grey card.
• Trailing slash on NEXT_PUBLIC_SITE_URL → // in every canonical/sitemap/robots URL.
• metadataBase missing → OG/canonical URLs don't resolve.
• Canonical pointing at a route that 404s (e.g. /tool vs the real /tools/tool).
• No sitemap/robots → poor indexing.
• Stock Next 404/error screen on a client-facing site → looks unfinished.