Technical SEO for Next.js and React sites: a diagnosis checklist

Most technical SEO problems on a Next.js site are not exotic. A canonical points at the wrong URL, a link only exists after a click, a sitemap lies about dates. The framework gives you good defaults, but it also lets you ship each of these defects without a build error or a failing test.

This guide is written for the person who has to find the cause: an in-house dev lead or a founder whose site is not indexing, or is indexing the wrong pages. Where we give examples, they come from our own site, which runs on Next.js 14 with the App Router. We audited it, found these problems, and fixed them. We make no claims about traffic or rankings here, only about what was wrong and how we checked.

Start with what a crawler receives, not what a browser shows. Fetch the page with `curl`, read the raw HTML, and compare it to the rendered page. Most of the sections below are variations on that one comparison.

Next.js can produce a page in several ways, and each one changes what is in the first HTML response. Search engines can render JavaScript, but rendering is a separate, later step and not a guarantee. Content and links that are already in the initial HTML are the safest to rely on.

For pages that exist to be found, such as service pages, guides and location pages, static or server rendering is the default to choose. Reserve client-only rendering for interactive tools behind a login, where indexing does not matter.

The subtler failure is content that is server-rendered in principle but mounted conditionally. The common pattern is an accordion that renders its panel only when open. The headings are in the HTML. The answers and any links inside are not.

The lesson is that a link a crawler cannot see passes nothing, however prominent it looks. Either render collapsed content in the HTML and hide it with CSS, or make sure every important URL is also linked from plain server-rendered markup. Use real `<a href>` links, not click handlers that call `router.push`.

The App Router exposes metadata through the `metadata` object or `generateMetadata`. Two parts of it cause most of the damage when they are wrong: `alternates.canonical` and `alternates.languages`.

A layout-level canonical cascades to every child

Metadata merges down the route tree. If a layout sets `alternates.canonical`, every child page that does not set its own inherits that value, and so declares the layout's URL as its canonical. On our site, a root-layout canonical meant pages without their own value all pointed at the same address. The fix is a rule: every page that should be indexed sets its own canonical in its own `generateMetadata`, and layouts do not set one.

Hreflang alternates must be reciprocal

If the English page lists a Spanish alternate, the Spanish page must list the English one back, and each page should reference itself. A one-way declaration is ignored. When we audited ours, we found pages with hreflang pointing at themselves in every language slot, mixed code styles (`en` alongside `en-US`), and sections with no hreflang at all. We settled on one policy: `en-US`, `es-US` and `x-default`, emitted only when a real translated counterpart exists.

Everything above can be checked in an afternoon with `curl`, a browser and Search Console. If the audit turns up structural problems across templates, technical SEO engineering is the part of our work that addresses them at the source.

In the App Router, `app/sitemap.ts` returns an array of URL entries, each with an optional `lastModified`. It is tempting to write `const now = new Date()` at the top and stamp it on everything. Ours did exactly that: a build-time date on most URLs, which told crawlers on every deploy that every page had just changed.

A build timestamp is not a modification date. Once a sitemap's dates are visibly unreliable, there is no reason for a crawler to trust them. Our policy now is that a URL carries `lastModified` only when a real, maintained date exists for it, such as a guide's editorial `dateModified`. Otherwise the field is omitted. The sitemap protocol treats `lastmod` as optional, so omission is always better than a fabricated value.

• List only canonical, indexable, 200-status URLs. Redirects, noindexed pages and 404s do not belong.
• Source dates from content (a CMS field or a data file), never from the build clock.
• If a page has no maintained date, leave `lastModified` out.
• Reference the sitemap from `app/robots.ts` so crawlers find it without Search Console.

JSON-LD emitted from a shared layout is convenient, and it is a frequent source of duplication. A layout outputs an `Organization` or `LocalBusiness` node, then a page template outputs another one, often with slightly different properties. The result is two entities describing the same business, which can disagree.

We measured this on our own site and found it on 93 of 140 URLs, from two causes. Some templates re-declared the provider with a type and properties instead of referencing it. A few pages declared a provider with no `@id`, creating a separate organization that competed with the real one. The fix was a single helper that returns `{ "@id": ORG_ID }`: the organization is described once, in one place, and every other node points to it. The count went to zero.

• Describe each entity once, with a stable `@id`, and reference it by `@id` everywhere else.
• Choose the schema type that matches reality. A business with no public premises should not claim a `LocalBusiness` address.
• Do not mark up content that users cannot see. FAQ markup should match visible questions and answers.
• Validate the rendered output of real pages, not just the component that builds it.

Dynamic and catch-all routes can turn every URL into a 200. If a route handler receives a slug it does not recognize and renders a page anyway, that is a soft 404: the content says "not found", the status says "fine". Call `notFound()` from `next/navigation` for unknown slugs, and the framework serves your not-found page with a 404 status.

There is a related trap with `generateStaticParams`. Known slugs get prerendered, but unknown ones still reach the server unless you restrict them. On our site we left `dynamicParams` at its default and had the route call `notFound()` itself. Setting `dynamicParams = false` made Next reject the request before the segment rendered, and the unstyled built-in 404 came back with none of our layout or tracking. Test by requesting a nonsense URL and reading the status and the HTML.

Retired URLs are a different case. If a page moved, add a permanent redirect in `next.config.js` so the old address passes to the new one. If it is gone for good, return a 404 or 410. Never redirect everything to the homepage.

1. 1Fetch raw HTML. Run `curl -s URL` for five representative templates. Confirm the title, canonical, main copy and key links are present without JavaScript.
2. 2Grep for important hrefs. Search the raw HTML for the URLs you most need crawled. Zero matches means a hidden or client-only link.
3. 3Read each canonical. Every indexable page should have a self-referencing canonical, set by the page and not inherited from a layout.
4. 4Check hreflang pairs. For each alternate, fetch the counterpart and confirm it points back.
5. 5Audit the sitemap. Confirm it lists only 200-status, indexable URLs, and that `lastModified` values are real or absent.
6. 6Inspect JSON-LD. Count entities per page. One organization node, referenced by `@id`, is the goal.
7. 7Probe status codes. Request a made-up slug at each route level and confirm a true 404. Request retired URLs and confirm a single redirect hop.
8. 8Compare against Search Console. Check the Page indexing report for patterns that match the defects above.

If your site was built by a team new to the framework, our web development and Next.js development pages describe how we build for crawlability from the start. The broader SEO engineering line and technical SEO cover audits and fixes, and the guides library has related reading.