How to ship one h1, title, meta description and JSON-LD on Next.js

Next.js hands you a Metadata API that writes your <title> and your meta description into the head automatically. It does not write your JSON-LD, and it does not write your <h1>. Those two are ordinary markup you render in a component, and on real sites that split is exactly where check C3 breaks. Across 120 Next.js sites in our own scan history, 34 of the 39 that miss C3 miss it on JSON-LD alone. This guide fixes all four signals in the App Router, in the order they actually fail.

Quick summary

Verified against the Next.js documentation at version 16.3.4, fetched from the framework's own docs site on 9 September 2026.

Three mechanisms, four signals

C3 wants four things on the page and accepts only one arrangement of them: a heading count of exactly one, a <title> with text in it, a meta description, and structured data in at least one JSON-LD block. Next.js covers two of the four from a single export and leaves the rest to you.

The Metadata API is the covered half. According to the generateMetadata reference, metadata objects from every segment in a route are merged shallowly from the root layout down to the page, and duplicate keys are replaced by the last segment that defines them. So a title.template in app/layout.tsx decorates every child title, and a description set in the root layout survives on any page that never sets its own.

JSON-LD is the uncovered half, and the docs are direct about it. The Next.js JSON-LD guide says, verbatim: "Our current recommendation for JSON-LD is to render structured data as a <script> tag in your layout.js or page.js components." There is no jsonLd metadata field. The framework's own site follows that advice: a plain fetch of the Next.js homepage on 9 September 2026 returned two application/ld+json blocks and both sit in the body, not the head.

The <h1> has no framework mechanism at all. Nothing in the Metadata API touches body markup, so a single visible heading is yours to get right.

What 120 Next.js sites actually get wrong

We grouped the C3 evidence strings across our own corpus on 9 September 2026, deduped to one latest scan per host on rubric 2026.08.2. C3 passes on 248 of 501 sites. Of the 120 detected as Next.js, 81 pass and 39 do not.

Read the first row twice. Twenty-three of the 39 failures have one <h1>, a title, a description and no structured data: the framework doing its job, and nobody reaching the one step it left out. Our WordPress guide found the mirror image, where 50 of 57 failures were the heading count.

Add the JSON-LD block Next.js will not add for you

Render it inside the page component, next to your content. According to the same guide, JSON.stringify does not sanitise strings used in injection attacks, so replace < with its unicode escape:

// app/blog/[slug]/page.tsx
export default async function Page({ params }) {
  const { slug } = await params
  const post = await getPost(slug)

  const jsonLd = {
    '@context': 'https://schema.org',
    '@type': 'Article',
    headline: post.title,
    description: post.excerpt,
    datePublished: post.date,
  }

  return (
    <article>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{
          __html: JSON.stringify(jsonLd).replace(/</g, '\\u003c'),
        }}
      />
      <h1>{post.title}</h1>
      {/* ... */}
    </article>
  )
}

Use a native <script> rather than next/script. In its own words, the guide notes that next/script is built for loading executable JavaScript, and structured data is not code.

Set title and description where the framework can see them

Both come from one export, and both have a rule that fails quietly.

// app/layout.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: { template: '%s | Acme', default: 'Acme' },
  description: 'One sentence describing the site, 150 to 160 characters.',
}

The quiet rule, according to the reference: the metadata object and generateMetadata exports are only supported in Server Components. Put export const metadata in a file carrying 'use client' and nothing is emitted, no warning appears, and C3 reports title: false. The reason given is that metadata has to resolve on the server before the page renders so it can go into the initial HTML response. Keep page.tsx a Server Component and move interactive parts into their own client file.

The streaming trap that hides your title from AI crawlers

When generateMetadata waits on runtime data, Next.js streams the page first. The reference says the resolved tags are then "appended to the <body> tag", and adds that this was verified with bots that execute JavaScript and inspect the full DOM. Crawlers that cannot run JavaScript get a blocking render instead, and Next.js decides which is which from the user agent.

That list is a single regular expression, HTML_LIMITED_BOT_UA_RE, in the framework's source. We fetched it on 9 September 2026 and matched it against the 33 crawler tokens in our own AI crawler inventory.

None of the eleven crawlers last measured as non-rendering appears on it. Googlebot is absent too, and correctly so, because it renders JavaScript. The others do not have that excuse. If your metadata defers to request time, add the crawlers you care about:

// next.config.ts
const config = {
  htmlLimitedBots: /GPTBot|ClaudeBot|PerplexityBot|CCBot|facebookexternalhit/i,
}
export default config

Or make the metadata static, which is faster and needs no list. The docs note that overriding this option can lengthen response times.

Write the h1 yourself, once per page

Thirteen of the 39 failing Next.js sites report a heading count other than one, ten of them zero. Both causes are layout-shaped: a root layout rendering a site name as <h1> while the page renders another, or a visible title that is styled text in a <div>. Put exactly one <h1> in the page component, keep the site name in the layout as a <p> or a <span>, and let the title tag carry the branding through title.template.

Scan it, then read the four booleans

Run the scan first. It reads all four signals in one pass and prints the evidence string C3 decided on:

npx aiscan-cli yoursite.com

Look at the C3 row. It returns h1: N, title: bool, meta description: bool, JSON-LD: bool, and only h1: 1 with all three true is a pass. You can paste the URL at AIScan instead if you would rather not install anything.

To check by hand, read the initial HTML the way a non-rendering crawler does:

URL=https://yoursite.com
curl -sL --compressed "$URL" -o /tmp/p.html
grep -c '<h1' /tmp/p.html
grep -o '<title>[^<]*</title>' /tmp/p.html
grep -c 'name="description"' /tmp/p.html
grep -c 'application/ld+json' /tmp/p.html

You want 1, one line of real text, 1, and at least 1. Validate the block itself with Google's Rich Results Test or the Schema Markup Validator, both named in the Next.js guide.

Where AIScan fits, and where it doesn't

C3 records whether a JSON-LD block is present. It does not report which @type you declared, whether the graph parses, or whether the description is unique across your pages. A page can pass C3 with an empty Organization stub. Treat the row as a floor, not a grade, and use a schema validator for the contents.

If this Next.js app is the front end for a headless WordPress install, the structured data, robots rules, sitemaps and llms.txt still come from the WordPress origin. ThinkRank keeps the schema graph, the robots rules, the sitemaps and llms.txt under one plugin, which spares you the usual argument between three of them over the same file, and it reads your current configuration straight out of Rank Math, Yoast, All in One SEO or SEOPress rather than making you type it again. Any of those four will write a decent JSON-LD graph if one is already installed. None of them can reach into your React tree.

Ship the JSON-LD before your next deploy

Add the script tag to your page component, confirm the metadata export is not in a client file, and scan again. The C3 row on the content checks page explains what each field means, and the Next.js platform page collects the rest of the stack. If your scan also reported low word counts or an empty body, the render is the deeper problem and our guide to React sites that go blank for AI crawlers covers it. For the same four signals on a CMS, see the WordPress version of this guide, and the full setup walkthrough wires up robots.txt, sitemap and feed alongside it. Everything else lives in the guides index.