Skip to content

laguagu/claude-code-nextjs-skills / skills/nextjs-seo

nextjs-seo

Verified

Next.js App Router SEO implementation and audits. Use for metadata and social images, sitemap/robots, canonicals and localization, structured data, Core Web Vitals evidence, AI crawler policy or search-indexing diagnosis. Not for general Next.js feature work unrelated to SEO.

FileKindSize
SKILL.mdskill md4.0 KB
references/ai-search.mdmarkdown7.1 KB
references/checklist.mdmarkdown2.6 KB
references/json-ld.mdmarkdown2.2 KB
references/metadata-api.mdmarkdown3.7 KB
references/sitemap-robots.mdmarkdown2.9 KB
references/troubleshooting.mdmarkdown4.3 KB

references/troubleshooting.md

View on GitHub
# SEO diagnosis

Start with an affected production URL and the exact observation. Compare the
complete served response, browser behavior and Search Console evidence;
these describe different layers.

## Indexing and crawl status

“Discovered – currently not indexed” says Google found the URL but has not
crawled it yet, typically because the crawl was rescheduled to avoid overloading
the site. “Crawled – currently not indexed” says a crawl did not result in
indexing. Neither status identifies a single cause or establishes a
content-length problem.

Use URL Inspection and the relevant indexing report to check fetch success,
crawl permission, noindex, declared and Google-selected canonicals. Inspect
redirects, status codes, duplicate intent and whether the page has a distinct
useful purpose. Check server/firewall logs when access is uncertain.

Change robots rules only after confirming the route should be public, and
preserve unrelated restrictions. A robots block can stop discovery of a
noindex directive. Indexing requests are optional follow-up after meaningful
fixes; repeated submissions do not guarantee indexing.

## Content missing from the served HTML

The browser hides this fault, because hydration fills the section in. Fetch the
production URL without JavaScript and search the response for a visible phrase
and a data value from each important section. Count fallback skeletons too.

With Cache Components (Next.js 16), check two causes:

- **The value is in the RSC payload (`self.__next_f`) but not in the markup.**
  The server had the data and the prerender left the Client Component out.
  Reading the clock or randomness during its render (`Date.now()`, `new Date()`,
  `Math.random()`, `crypto.randomUUID()`) stops the prerender at that point, and
  the nearest Suspense fallback is what the HTML holds. Libraries do this too:
  TanStack Query v5 reads `Date.now()` in `useQuery` for a numeric `staleTime`
  and when it builds a query from `initialData` without `initialDataUpdatedAt`,
  and `dehydrate()` reads it as well. A `<Suspense>` boundary silences the
  build's prerender error by deferring the content, so the error going away does
  not mean the content is in the HTML. Keep the read out of server render, for
  example `staleTime: isServer ? "static" : ms` with seeded `initialData` and an
  `initialDataUpdatedAt` the server passed in, such as `Date.parse(serverTime)`
  (tested on Next.js 16.3 with TanStack Query 5.103), or move it to an effect.
- **The value is in neither.** Check the section's `cacheLife`: `revalidate: 0`,
  `expire` under 5 minutes or `stale` under 30 seconds exclude it from
  prerenders, and it resolves at request time. `stale` under 5 minutes also keeps
  it out of the App Shell. For content a crawler must read, keep `stale` and
  `expire` at 5 minutes or more and refresh live values on the client.

## Missing or wrong metadata

Compare source and the complete production response for the installed
metadata-streaming mode and relevant bot. Check inheritance, file precedence,
relative URL resolution and the correct deployment origin.
See [metadata-api.md](metadata-api.md).

## Content is stale

Trace the actual publication, cache and invalidation path for the page,
metadata and sitemap. A database read or changed source file is not proof the
deployed route refreshed. Test the real update rather than substituting a
generic cache lifetime.

## HTML is correct but interaction fails

Indexable HTML does not prove hydration. Directly open the route in a
production browser and test buttons, forms and Suspense content. Inspect
console errors, streamed RSC responses, failed assets, client/server initial
state and the deployed proxy.

Test both a direct production load and client navigation: a partially
prerendered route (for example one reading `searchParams`) can serve correct
SEO HTML yet leave its Suspense content unhydrated on a direct load while
working after client navigation. An inactive browser tab can also delay streamed reveal;
rule that out before reporting a failure. Preserve a reproducible case and
investigate the installed framework/configuration.

Use [URL Inspection documentation](https://support.google.com/webmasters/answer/9012289)
for report semantics. State missing credentials, reports or verified bot logs
as limitations instead of inferring them from unrelated exports.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall