Claude Code SEO: Build Search-Ready Sites From the Start

Claude Code is Anthropic’s agentic CLI for coding. Unlike a no-code builder or a hosting platform, it doesn’t impose a stack or generate opinions about SEO. It does exactly what you ask. That’s the leverage point: if you ask well, you get a site that search engines and AI crawlers can actually read. If you don’t, you get a fast, well-structured SPA that’s effectively invisible.

The good news is that the ask isn’t complicated. You need to specify the right framework, tell Claude Code what SEO elements to generate, and capture those instructions somewhere persistent so every future session follows the same rules. This guide covers all three.

Why Claude Code’s SEO output depends on your prompt

Claude Code has no default SEO stance. It will reach for what’s familiar or efficient for the task at hand, which often means a React SPA if you ask for a fast frontend with minimal configuration. A React SPA with client-side rendering is where SEO quietly dies: the server returns near-empty HTML, JavaScript runs in the browser to populate the page, and crawlers (particularly AI crawlers like GPTBot and PerplexityBot) see almost nothing.

The fix isn’t complicated, but it has to be explicit. Tell Claude Code what framework to use and why, or it won’t know to choose SSR or SSG over a bare CRA/Vite setup. Once you’ve established the framework, every other SEO requirement follows from it.

Compare the two outcomes:

Approach	What crawlers see	SEO result
Bare React SPA (no prompt guidance)	`<div id="root"></div>`	Near-zero indexable content
Next.js (App Router) or Astro (SSG)	Full HTML on first byte	Indexable, rankable pages

This is covered in more depth in the platform SEO overview and in the dedicated Next.js SEO and Astro SEO guides.

Step 1: Specify an SEO-capable framework

The first thing to get right is the framework choice. Tell Claude Code which one you want and give it the SEO reason so it doesn’t substitute something lighter.

Next.js (App Router) is the right choice for dynamic content, authenticated routes, or anything that needs server-side data fetching at request time. Every page renders on the server and ships full HTML to the client. The Metadata API lets you define titles, descriptions, Open Graph tags, and canonical URLs per route in a type-safe way.

Astro is the right choice for mostly-static content (blogs, marketing sites, docs). It ships zero JavaScript by default, generates fully static HTML at build time, and supports markdown frontmatter for per-page metadata. It’s the fastest option for content-heavy sites where crawlability is the top priority.

Both are well within Claude Code’s competence. The risk is not that it can’t build them, it’s that it defaults to something else if you don’t ask.

A prompt that establishes this upfront:

Build this project with Next.js 14 (App Router). Use server-side rendering 
or static generation for all pages. Do not use client-side-only rendering 
for any content that needs to be indexed.

Step 2: Instruct it to generate per-page SEO elements

Framework choice is necessary but not sufficient. You also need to tell Claude Code to generate the specific elements that make pages rankable. Left unspecified, it may build pages without titles, ship a single meta description for the whole site, or skip schema entirely.

Page titles and meta descriptions

In Next.js App Router, the right pattern is a generateMetadata export per route. Ask Claude Code to generate it for every page, not just the homepage.

// app/blog/[slug]/page.tsx
export async function generateMetadata({ params }) {
  const post = await getPost(params.slug);
  return {
    title: post.title,
    description: post.excerpt,
    alternates: {
      canonical: `https://example.com/blog/${params.slug}`,
    },
    openGraph: {
      title: post.title,
      description: post.excerpt,
    },
  };
}

In Astro, this lives in frontmatter and gets rendered via a shared <BaseHead> component. Ask Claude Code to build that component once and use it on every layout.

Canonical tags

Tell Claude Code to include a canonical tag on every page. Without it, paginated content, filtered URLs, and syndicated pages can all create duplicate-content problems that split ranking signals.

Sitemap and robots.txt

Ask for these explicitly. In Next.js, app/sitemap.ts exports a function that returns your URL list. In Astro, the @astrojs/sitemap integration generates it at build time. Either way, Claude Code needs to be told to do it.

// app/sitemap.ts (Next.js App Router)
export default function sitemap() {
  return [
    {
      url: 'https://example.com',
      lastModified: new Date(),
    },
    {
      url: 'https://example.com/about',
      lastModified: new Date(),
    },
  ];
}

Semantic HTML and real anchor links

Client-rendered navigation often uses JavaScript click handlers instead of <a href> elements. Ask Claude Code to use real anchor links throughout. Navigation items, breadcrumbs, internal links, and pagination all need <a href> tags for crawlers to follow them.

Ask for semantic heading structure too: one <h1> per page, logical <h2> and <h3> hierarchy, no skipped levels.

JSON-LD schema

Schema markup is one of the clearest signals for both Google and AI engines. Ask Claude Code to add a JSON-LD block to relevant pages. For an article or blog post:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Your Article Title",
  "author": {
    "@type": "Person",
    "name": "Author Name"
  },
  "datePublished": "2026-05-24",
  "publisher": {
    "@type": "Organization",
    "name": "Your Brand",
    "logo": {
      "@type": "ImageObject",
      "url": "https://example.com/logo.png"
    }
  }
}
</script>

For a product page, use @type: "Product" with offers, aggregateRating, and image. For a local business, use LocalBusiness with address and opening hours. Schema tells AI search engines what the page is about at a structured level, which matters for AI citations (more on that below).

Step 3: Lock the rules in a CLAUDE.md file

The real productivity win is making these requirements permanent. Claude Code reads a CLAUDE.md file in your project root at the start of every session. Instructions in that file apply to all future work in the project without you having to repeat them.

Add an SEO section to your project instructions:

## SEO requirements

- Framework: Next.js 14 App Router (or Astro for static sites)
- Every page must export generateMetadata (Next.js) or set frontmatter 
  title/description (Astro)
- Every page must have a canonical tag pointing to its own URL
- Use real <a href> anchor links for all navigation and internal links
- Heading structure: one <h1> per page, logical h2/h3 hierarchy
- sitemap.ts (Next.js) or @astrojs/sitemap (Astro) must be configured
- robots.txt must be present and allow all crawlers
- Add JSON-LD schema blocks to article, product, and key landing pages
- No client-only rendering for indexable content

This is the same mechanism that makes Cursor SEO consistent across sessions. The instructions live in the repo, not in your head, and every new chat inherits them.

This site is maintained with Claude Code, with SEO rules in the project instructions. Every new page gets metadata, schema, and correct heading structure without a checklist review.

Step 4: Use Claude Code to audit an existing site

Claude Code can also work backwards on a site that already exists. Ask it to fetch raw HTML from your live URLs and report what’s missing. This is more reliable than a GUI audit tool because it reads the actual server response, not a rendered browser view.

A prompt that works well:

Fetch the raw HTML (not the rendered DOM) from these URLs and report:
1. Missing or duplicate page titles
2. Missing or generic meta descriptions
3. Pages where the visible content is absent from the raw HTML 
   (client-rendered)
4. Missing canonical tags
5. Missing or malformed JSON-LD schema
6. Navigation links that use JS click handlers instead of <a href>

URLs to check:
- https://example.com
- https://example.com/about
- https://example.com/blog/first-post

The “visible content absent from raw HTML” check is the most important one. If Claude Code fetches a page and the <body> contains only a <div id="root"> with no text, the content is client-rendered and crawlers won’t see it. That’s the issue covered in detail in the single-page application SEO guide.

How this affects AI search citations

Being cited in ChatGPT, Perplexity, and Google AI Overviews depends on something narrower than general SEO: the AI crawler has to be able to read the page, and the content has to be structured clearly enough that the AI can extract a confident answer.

Most AI crawlers do not execute JavaScript. GPTBot, PerplexityBot, and Google’s AI crawler all primarily index server-rendered HTML. A client-rendered SPA is effectively invisible to them regardless of how much content it contains.

Beyond rendering, structured content helps. Clear <h2> and <h3> headings let AI models identify the topic of each section. JSON-LD schema gives them explicit signals about entity type, author, date, and publisher. A well-formed FAQ or how-to schema can surface directly as an AI answer.

The AI SEO guide covers this in detail, including how to monitor whether AI engines are actually citing your pages and which schema types have the most impact.

When you ask Claude Code to generate proper schema and server-rendered HTML, you’re optimising for AI citation, not just Google rankings. The two requirements are almost identical, which is why getting the prompting right once pays off across all channels.

SEO instructions to add to your project

Copy this into your CLAUDE.md or project instructions file:

## SEO

- Use Next.js App Router or Astro (never a bare CRA/Vite SPA for indexable content)
- generateMetadata (Next.js) or frontmatter title/description (Astro) on every page
- Canonical tag on every page pointing to its canonical URL
- All navigation and internal links must use <a href>, not JS event handlers
- One <h1> per page; logical h2/h3 hierarchy
- sitemap.xml auto-generated (sitemap.ts or @astrojs/sitemap)
- robots.txt present, allowing all crawlers by default
- JSON-LD schema on article, product, FAQ, and key landing pages
- No client-side-only rendering for content that should be indexed
- Open Graph tags (og:title, og:description, og:image) on every page

What to do next

If you’re starting a new project, paste the instructions above into your CLAUDE.md before your first session. Claude Code will follow them from the first file it creates.

If you’re auditing an existing site, run the prompt in Step 4 on your five most important pages first. Client rendering and missing metadata are usually the biggest gaps, and both are fixable in a single session.