AI AI Tools Guidebook
AI Tool Tutorials

Use AI to Audit an Astro Site for SEO Bugs

Astro-specific AI audit prompts for routing, sitemap, hreflang, output mode and RSS — verified against Astro 6 (June 2026).

Published: Updated: Author: AI Productivity Guide Team 🌐 查看中文版本

Astro’s flexibility — two output modes, optional integrations, content collections, per-page prerender opt-out — is also where most teams accumulate silent SEO bugs. A sitemap missing a route, an hreflang missing a locale, an RSS feed pointing at a stale base URL: none of these surface until traffic starts dropping. This walks through framework-specific audit prompts that catch the Astro-shaped problems a generic site audit never looks for, verified against the Astro 6 config shape that has been stable since March 2026.

TL;DR

Feed an AI agent (Claude Code, Cursor, or Codex) your astro.config.mjs plus a find src/pages -type f tree, then run four scoped audits in order: routing → sitemap → hreflang → RSS. Each audit cross-checks one Astro subsystem against the others and cites a specific file or URL. Fix blockers, rebuild, re-run. The single most common silent bug on bilingual Astro sites is hreflang alternates missing from the sitemap, and the most common Astro 5→6 migration miss is a leftover output: 'hybrid', which no longer exists.

What this covers

Astro-specific audit prompts aimed at the integration layer teams ship and forget: astro.config.mjs, src/pages/, sitemap output, hreflang alternates, output mode, and RSS. The audit is shaped around how Astro actually builds — not generic “is your site good” advice.

Two things to pin down before you write a single prompt:

  • Output mode. As of Astro 5 (and unchanged in Astro 6), there are exactly two: output: 'static' (the default) and output: 'server'. The old output: 'hybrid' was removed in v5 — its behavior is now the default static mode, and any single route opts into on-demand rendering with export const prerender = false. If your config still names hybrid, that is finding #1.
  • i18n strategy. Either Astro’s built-in i18n config or a community integration. The default prefixDefaultLocale: false means your default-locale URLs have no /en/ prefix while every other locale does — which changes what the route and sitemap audits should expect.

Who this is for

Indie devs and small teams running Astro content or marketing sites — especially bilingual sites, where hreflang and route generation interact in non-obvious ways.

When to run it

  • Before or after a large content addition.
  • After an Astro major upgrade (the 4→5→6 jump changed config shape, removed hybrid, and moved content collections onto the Content Layer loader API).
  • After adding or removing an integration.
  • Quarterly, as a standing check — integration version bumps quietly drift the config.

After the site-level pass, drill into the AI category-page audit tutorial — duplicate intros, weak internal linking, and broken pagination usually only surface when you audit category pages specifically.

Before you start

  • Give the AI read access to astro.config.mjs and src/pages/. The audit reads both.
  • Confirm your output mode. With static (default), every page is prerendered unless it exports prerender = false; with server, the reverse. The right prompts differ.
  • Have your locale list ready. For a bilingual en/zh site, the hreflang audit needs to know both are expected and which is the default.

Step by step

  1. Feed astro.config.mjs plus the page tree (find src/pages -type f) to the agent as context.

  2. Routing audit. Astro errors loudly on a dynamic route with no getStaticPaths (GetStaticPathsRequired), but it fails silently when a slug your code constructs never appears in getStaticPaths() — that path simply 404s on the live site while the build passes. Prompt:

Given astro.config.mjs and the src/pages tree, list every
route Astro will generate at build. Flag any: dynamic
[slug] or [...slug] routes with no getStaticPaths export,
getStaticPaths returning an empty array, two files
resolving to the same URL, and (given i18n.defaultLocale
and prefixDefaultLocale) any locale prefix that is missing
or inconsistent with that setting.
  1. Sitemap audit. @astrojs/sitemap emits sitemap-index.xml plus numbered sitemap-0.xml files (it chunks at 45,000 URLs each). Its i18n block is what generates the <xhtml:link rel="alternate" hreflang="..."> entries — if that block is absent, no alternates ship, no matter what your page <head> says. Prompt:
Inspect the @astrojs/sitemap config. Confirm `site` is the
production origin, and report whether the i18n block (with
defaultLocale + locales) is present. List the URLs the
sitemap will include and cross-check against the route
list from step 2. Flag: routes in the sitemap but not
generated, routes generated but excluded, hreflang
alternates missing for bilingual URLs, and any lastmod or
changefreq set by a serialize() hook that looks wrong.
  1. Hreflang audit. Astro can ship hreflang in two places — the page <head> and the sitemap. They must agree. Prompt:
For each bilingual page pair, confirm: both pages exist;
each <link rel="alternate" hreflang="..."> in one page's
head points at the other; a self-referential alternate and
an x-default are present; and the same alternates appear in
the sitemap's xhtml:link entries. Report head/sitemap
mismatches separately.
  1. RSS audit (if you ship a feed):
Read the @astrojs/rss usage. Confirm: the feed's `site`
matches the production origin, every item has a pubDate,
the feed is linked from <head> via a rel="alternate"
application/rss+xml link, and item links are absolute, not
relative.

  1. Triage findings into blocker (broken page or wrong canonical), warn (missing nice-to-have), info (style). Fix blockers first.

  2. Run astro build, then re-run the audits against the built dist/. Sitemap and hreflang fixes only show up after a fresh build — source and output drift until you rebuild.

What “good” findings look like

The audit is only useful when each finding is reproducible. Hold every result to this bar:

Vague finding (reject)Actionable finding (keep)
“Sitemap is wrong""sitemap-0.xml lists /en/foo but src/pages/en/foo.astro does not exist"
"hreflang is broken""/en/pricing head links hreflang=zh but the sitemap entry has no xhtml:link for zh"
"Some routes 404""[...slug].astro builds 0 paths because getStaticPaths() returns []”

If the audit says “X is missing” but dist/X/index.html exists after a build, the AI was reading stale source — rebuild and re-run, do not patch on a false positive.

Common mistakes

  • Asking the AI to “review the site” with no config in context — you get generic SEO advice unrelated to Astro.
  • Auditing source files without rebuilding — sitemap output and rendered HTML drift from source until you astro build again.
  • Leaving output: 'hybrid' in the config after a v5/v6 upgrade — it was removed; the build either errors or silently ignores it. Use static plus export const prerender = false per route.
  • Skipping the hreflang audit on bilingual sites — missing sitemap alternates is the single most common silent Astro SEO issue.
  • Trusting the i18n sitemap block to fix head-level hreflang — they are independent. The sitemap audit and the hreflang audit both have to pass.
  • Treating getStaticPaths returning [] as harmless — those are routes that ship as 404s.

Wiring it into CI

Save the four prompts separately so you can re-run only the subset that changed. Then turn the recurring check into code: a small CI step that runs astro build and diffs the generated route list (or sitemap-0.xml) against a committed expected manifest. Once that exists, the AI audit stops being “what’s broken?” and becomes “the manifest changed — is the change intentional?”, which is a far cheaper question to answer on every PR.

FAQ

  • Static vs server — does the audit change?: Yes. With output: 'server', pages render at request time unless they export prerender = true, so the route list the AI infers from files alone can be incomplete. Tell the agent your output mode and which routes opt out of the default.
  • Does output: 'hybrid' still exist?: No. Astro 5 removed it and Astro 6 (stable since March 2026) keeps it gone. The old hybrid behavior is the default static mode; opt individual routes into on-demand rendering with export const prerender = false.
  • My site uses a community i18n integration, not built-in i18n.: Same audits, different config path. Point the AI at the integration’s config and tell it which locale is the default; the prompts don’t assume the built-in router.
  • How does this relate to the content audit?: This checks framework-level wiring (routes, sitemap, feeds). The content audit checks per-file frontmatter. Run both — see the Astro content audit tutorial.
  • Can the AI write the fix?: Yes — ask “show me the minimum patch to fix finding N.” Config changes (adding the sitemap i18n block, fixing a getStaticPaths slug) are where it’s fastest and most accurate.
  • Does this work on Starlight or other Astro templates?: Yes, with a caveat: templates may abstract the config behind their own options. Point the AI at the underlying astro.config.mjs and any integration config the template exposes.

Tags: #AI coding #Tutorial

Related Articles