SEO for a Headless CMS

TL;DR — A headless CMSA content management system that separates the content repository from the presentation layer, delivering content via API to any front-end framework rather than rendering HTML server-side itself. It doesn't specify the rendering mode, hosting, cache, preview security, or publishing workflow — those are separate decisions. splits where you write content from where it gets shown. That split is fine for SEO — but only if the website part hands search engines fully-built HTML. The big rule: render your pages on a server or at build time (SSR or SSG), not entirely in the visitor’s browser (CSR). And all the SEO stuff a WordPress plugin used to do for you — titles, sitemapsA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing., robots.txtA plain-text file at the root of a host that tells crawlers which URLs they may and may not request. It controls crawling, not indexing — a blocked URL can still be indexed if it's linked from elsewhere. — you now have to set up yourself.

What “headless” actually means

In a traditional setup like WordPress, the place you write content and the place that turns it into a web page are the same system. A headless CMSA content management system (CMS) is software that lets users create, manage, and publish digital content — like blog posts and pages — without writing raw code. WordPress, Drupal, and Joomla are the most common open-source CMS platforms. pulls those two jobs apart. The CMS becomes just a content storehouse (Contentful, Sanity, Strapi, and others), and a separate website — built with a framework like Next.js, Nuxt, Astro, or Gatsby — fetches that content and builds the actual pages. Evidence for this claim A headless CMS separates content management from the presentation frontend and exposes content through APIs. Scope: Contentful as a representative headless CMS architecture. Confidence: high · Verified: 2026-07-14 Contentful: What is a headless CMS?

People worry that this is bad for SEO. It isn’t, by itself. The CMS sitting in the back has almost no effect on your rankings. What matters is how the front part builds the page.

The one decision that matters: rendering

When someone (or GooglebotGooglebot is Google's web crawler — the software that fetches pages so Google can index and rank them. It comes in two variants, Googlebot Smartphone (primary, under mobile-first indexing) and Googlebot Desktop, and runs an evergreen Chromium renderer.) asks for a page, where does the finished HTML get made? There are basically two safe answers and one risky one:

• At build time (SSG) — pages are built ahead of time into plain HTML files. Fast and search-friendly.
• On a server, per request (SSR) — the server builds the full page and sends it. Also search-friendly and always fresh.
• In the visitor’s browser (CSR) — the server sends a near-empty shell, and JavaScript fills it in afterward. This is the risky one for SEO.

Google can run JavaScript, but renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. is a separate processing stage and JavaScript can still fail or be blocked. Other crawlersA crawler — also called a spider or bot — is an automated program that fetches web pages, extracts their links, and queues new URLs to visit. Search engines use crawlers to discover and download content for their index. have different renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. capabilities, so server-rendered or pre-rendered HTML is the most portable way to deliver critical content. Evidence for this claim Google processes JavaScript through a rendering stage, and blocked or failed resources can prevent expected content from rendering. Scope: Google Search; other crawlers have their own capabilities. Confidence: high · Verified: 2026-07-14 Google: JavaScript SEO basics

The “where did my SEO settings go?” problem

In WordPress, a plugin like Yoast quietly handled your titles, meta descriptionsThe meta description is an HTML head tag — `<meta name=\"description\" content=\"…\">` — that suggests a short summary of the page for the search snippet. It's not a Google ranking factor, and Google rewrites it the majority of the time, but a good one can still lift click-through., sitemapA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing., and canonical tagsA rel=\"canonical\" annotation — in the HTML <head> or an HTTP Link header — that tells search engines which URL is the preferred version of duplicate or near-duplicate content.. A headless site has no plugin layer. That means a developer has to deliberately:

• Add SEO fields (title, description, etc.) to the content model in the CMS.
• Wire those fields into the page’s HTML.
• Create a sitemap and a robots.txtA plain-text file at the root of a host that tells crawlers which URLs they may and may not request. It controls crawling, not indexing — a blocked URL can still be indexed if it's linked from elsewhere..

None of this is hard — it just won’t happen on its own. A lot of “my headless site lost its SEO” stories are really “nobody rebuilt the stuff the plugin used to do.”

A couple of things that quietly break

• Preview/staging sites getting indexedStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed.. Headless setups often spin up public preview URLs. If Google finds them, it can index a whole duplicate copy of your site. These need to be blocked from indexingStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed..
• Links that aren’t real links. Search engines only follow real <a href> links. A clickable <div> that navigates with JavaScript won’t be crawled.

Want the full version — the four rendering modes compared, canonical tagsA rel=\"canonical\" annotation — in the HTML <head> or an HTTP Link header — that tells search engines which URL is the preferred version of duplicate or near-duplicate content., sitemaps, the ISR stale-content trap, Bing, and migrations? Switch to the Advanced tab.

TL;DR — In headless SEO, architecture is the product: the CMSA content management system (CMS) is software that lets users create, manage, and publish digital content — like blog posts and pages — without writing raw code. WordPress, Drupal, and Joomla are the most common open-source CMS platforms. backend is nearly SEO-neutral, and the frontend’s renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. mode decides everything. SSG and SSR ship fully-rendered HTML and are the safe choices; CSR is the riskiest; ISR carries a stale-on-first-request-after-revalidation trap. Everything Yoast did automatically — metadata, canonicals, sitemapsA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing., robots.txtA plain-text file at the root of a host that tells crawlers which URLs they may and may not request. It controls crawling, not indexing — a blocked URL can still be indexed if it's linked from elsewhere. — you now build explicitly, and canonical logic fragments across CMS → framework → component, so set it at the renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. layer from one SITE_URL. The same split applies to locale routing/hreflangHreflang is an annotation (in HTML, HTTP headers, or XML sitemaps) that tells search engines which language and optional region a page targets, and which alternate versions exist. It only works when every page in the cluster references all the others. and to preview access (authenticate first; noindex is secondary, not access control). Google deprecated dynamic rendering (use SSR/SSG/hydrationActivating server-rendered HTML in the browser by attaching JavaScript handlers.), AI-crawlerA crawler — also called a spider or bot — is an automated program that fetches web pages, extracts their links, and queues new URLs to visit. Search engines use crawlers to discover and download content for their index. rendering varies by provider, and publish/unpublish events need a webhook-triggered cache purge, not a timer.

Architecture is the product

A headless CMSA content management system that separates the content repository from the presentation layer, delivering content via API to any front-end framework rather than rendering HTML server-side itself. It doesn't specify the rendering mode, hosting, cache, preview security, or publishing workflow — those are separate decisions. is just a backend: content storage, a content model, an editing UI, and an API. The frontend — Next.js, Nuxt, Gatsby, Astro, SvelteKit, Remix — is a separate application that fetches content over REST or GraphQL and renders it. The single most useful mental model here is that the CMS you pick has almost no direct SEO impact; the rendering decisions in the frontend determine everything. Every headless SEO conversation should start with one question: how is the frontend rendering this content? Evidence for this claim A headless CMS supplies content through APIs while a separate frontend controls how pages are rendered. Scope: Contentful as a representative headless CMS architecture. Confidence: high · Verified: 2026-07-14 Contentful: What is a headless CMS?

That’s why “headless is bad for SEO” is the wrong frame. Headless is neutral. A well-built headless site on SSR or SSG, with disciplined metadata, will outperform a neglected WordPress install. A headless site that defaults to client-side rendering and never rebuilt its metadata layer will quietly fall apart. This is the same point I make in my JavaScript SEO guide: the web moved off plain HTML, and as an SEO you can embrace that rather than fight it.

Who owns what: CMS, API, and frontend

“The CMS is nearly SEO-neutral” is the right instinct, but it’s not license to skip a real ownership map. A content model stores structured types and fields — that’s it. It doesn’t prove titles, canonicals, schema, or links actually get emitted; that only happens once the frontend does its job. Evidence for this claim A headless CMS content model defines structured types and fields, but the consuming frontend owns URL routing and the rendered HTML that titles, canonicals, schema, and links depend on. Scope: Contentful content-model docs plus Next.js metadata docs as representative frontend evidence. Confidence: high · Verified: 2026-07-18 Contentful: Data model Next.js: Metadata and OG images Splitting responsibility explicitly avoids the two failure modes I see most: nobody owns a piece (it silently never gets built), or three layers all think they own it (it fragments, the way canonicals do below).

Also distinct: which API you call. Delivery, management, and preview APIs have different publication and authorization semantics. Production rendering has to use the published-content API only — never a management or preview token/endpoint, which can leak unpublished content or write access into a public response. Evidence for this claim Delivery, management, and preview APIs have different publication and authorization semantics; production rendering must use the published-content API and must not expose management or preview tokens. Scope: Contentful API basics and Preview API docs as representative headless-API evidence. Confidence: high · Verified: 2026-07-18 Contentful: API basics Contentful: Content Preview API overview

How Google processes a JavaScript page

Google processes JavaScript pages through crawlingCrawling is how search engines use automated bots (like Googlebot and Bingbot) to discover URLs and download pages. A page has to be crawlable to be indexed, but crawling on its own isn't a ranking factor., rendering, and indexingStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed.. Pages that depend on client rendering do not expose their final content in the initial HTML response, while SSR and SSG put that content in the response before browser execution. Evidence for this claim Google crawls, renders, and indexes JavaScript pages, while server-side or pre-rendered HTML exposes content in the initial response. Scope: Google Search JavaScript processing; indexing is not guaranteed. Confidence: high · Verified: 2026-07-14 Google: JavaScript SEO basics

Two related facts matter at scale. Google cannot render JavaScript from blocked files, so required .js and .css resources need to remain crawlable. Rendering JS is genuinely expensive — at Ahrefs we crawl billions of pages a day and rendering JavaScript pages eats a serious chunk of our infrastructure — which is a good reminder that “GooglebotGooglebot is Google's web crawler — the software that fetches pages so Google can index and rank them. It comes in two variants, Googlebot Smartphone (primary, under mobile-first indexing) and Googlebot Desktop, and runs an evergreen Chromium renderer. can render it” is not the same as “you should make Googlebot render it.”

The AI-crawler reality

This is the 2026 wrinkle most headless SEO advice still misses. Most AI crawlersAI crawlers are bots from AI companies that fetch web pages to train language models, build AI-search indexes, or answer live user questions. They come in three categories, each with its own user-agent tokens and its own robots.txt controls. — the fetchers behind ChatGPT, Perplexity, and similar — do not execute JavaScript. A Vercel study put it bluntly: none of them render client-side content, so if your critical pages ship as JavaScript-dependent SPAs, those pages are effectively invisible to AI searchAI search uses large language models and retrieval-augmented generation (RAG) to synthesize an answer from multiple sources rather than returning a ranked list of links. Examples include Google AI Overviews, ChatGPT Search, and Perplexity.. Google’s own rendering team has said they render essentially all HTML pages, but that’s Google. For AI visibility, SSR/SSG isn’t a nice-to-have; it’s the price of entry.

The four rendering modes

SSG — Static Site Generation. HTML is generated at build time and served as static files from a CDN. Best-case SEO: fully-rendered HTML on first request, very fast TTFBTime to First Byte — the time from the start of a request to when the first byte of the response arrives. It's a diagnostic metric (not a Core Web Vital) and a major input to FCP and LCP; ≤0.8 s is good.. The tradeoff is freshness — new or changed content requires a rebuild, and large sites get slow builds (ISR partially solves this). Gatsby and Astro are SSG-first; Next.js supports it per route; Hugo is a classic.

SSR — Server-Side Rendering. HTML is rendered per request on a server or edge function. Excellent SEO: always-fresh, fully-rendered HTML on first request. The tradeoff is infrastructure cost and slightly higher TTFB than static files. Next.js, Nuxt, SvelteKit, and Remix all do this.

ISR — Incremental Static Regeneration. Static pages regenerate in the background after a revalidation interval. Good SEO most of the time, with one genuine trap (next section). Primarily a Next.js feature; Nuxt has analogues.

CSR — Client-Side Rendering. A minimal HTML shell ships, then JavaScript in the browser fetches content and builds the DOM. This is the worst SEO option: Googlebot must queue the page for the render wave, timing is unpredictable, and AI crawlersA crawler — also called a spider or bot — is an automated program that fetches web pages, extracts their links, and queues new URLs to visit. Search engines use crawlers to discover and download content for their index. and many other bots see only the empty shell. CSR is acceptable for highly interactive dashboards or authenticated-only pages that are behind a login and shouldn’t be indexed anyway — not for content you want found. Raw React or Vue SPAs without Next.js/Nuxt land here by default.

The ISR stale-content trap

This one is novel enough that it’s worth its own section. With ISR, when the revalidation window expires:

1. The next incoming request triggers background regeneration.
2. That request — which could be Googlebot — still receives the stale cached page.
3. The fresh version is only served on the following request.

For frequently-crawled pages, this can mean Googlebot routinely sees content one revalidation cycle behind. For genuinely volatile data (prices, stock levels), SSR is the safer call. ISR is a great middle ground for content that changes on the order of hours or days, not seconds.

Dynamic rendering is deprecated

Years ago — including in talks I gave around 2019 — dynamic rendering (serving a prerendered version to bots via something like Puppeteer or Rendertron) was a reasonable workaround. Google has since reversed that stance. Officially, “dynamic rendering was a workaround and not a long-term solution,” and it “creates additional complexities and resource requirements.” Google now recommends server-side rendering, static rendering, or hydration instead. Note the nuance: dynamic rendering is not automatically cloaking — Google won’t penalize it just for existing, and it only crosses into cloaking if you serve completely different content to users vs. crawlers. But “not cloaking” and “officially deprecated” are both true at once. Don’t reach for it on a new build.

Metadata — rebuilding what the plugin did

In WordPress, Yoast or Rank Math auto-generated a title and description for every page. Headless has no plugin layer, so the work is explicit:

1. Add SEO fields to the CMS content model — title, description, robots override, canonical override, Open GraphOpen Graph (OG) tags are `<meta>` elements in a page's head, defined by the Open Graph protocol (ogp.me, created by Facebook), that describe a page as a shareable object — its title, description, image, URL, and type. They control how a link preview card looks when the page is shared on Facebook, LinkedIn, Slack, Discord, WhatsApp, and iMessage. They are not a direct Google ranking factor, though Google reads og:title, og:image, and og:site_name as inputs to how a result appears. fields.
2. Map those fields into the <head> of each page template from the API response.
3. Use framework-native head management — Next.js generateMetadata (App Router) or the metadata export; Nuxt useSeoMeta; Gatsby’s <Seo> component / react-helmet; Astro’s <head> in layout files.

Common bugs: metadata injected client-side is seen late (post-render) instead of immediately; a single shared layout canonical that never updates per page (so everything canonicalizes to the homepage); and in Next.js App Router, a missing metadataBase producing broken relative canonical URLs. The reliability rule is simple — HTML-level metadata beats JS-injected metadata, because Google sees it on the first fetch. Modules like Helmet and Head are fine for this, but get the critical tags into the server-rendered HTML.

The content model itself needs rules, not just fields, or the mapping step above breaks silently:

• Required vs. optional per field. Title and canonical override should be required (or auto-derived) so a page can never publish with an empty <title>. Description and OG fields can stay optional with a frontend fallback.
• A defined fallback chain. If an SEO field is empty, decide up front what the frontend substitutes — a body excerpt for description, the H1 for title — and implement that in the mapping layer, not ad hoc per template.
• Locale fallback is a separate rule from field fallback. The content API can substitute a default-locale value when a translation is missing; that’s useful for the body, but an SEO field silently falling back to another locale’s title/description is usually wrong and worth flagging separately.
• Escaping at the mapping step. CMS text fields commonly allow HTML or rich text; strip or escape that before it lands in a <title>, <meta>, or JSON-LDJSON-LD (JavaScript Object Notation for Linked Data) is a script-based structured data format, typically paired with the schema.org vocabulary to describe page content for search engines and AI systems. Google recommends it over Microdata and RDFa because it's the easiest format to implement and maintain at scale — but all three work, and structured data isn't a ranking signal. string, or you’ll ship broken markup or, worse, injected script.
• Acceptance test per route type. Before launch, confirm what the rendered <head> looks like for a normal entry, an entry with an empty optional field, and an entry queried in a locale it has no translation for — three different code paths that a single happy-path test won’t catch.

Canonical fragmentation — a headless-specific risk

In WordPress the canonical lives in one place. In headless it’s split across three layers: the CMS stores a slug, the framework assembles the full URL from that slug plus environment config, and a component renders the <link rel="canonical"> tag. If any layer drifts — a slug changes, a route pattern changes, a component gets refactored — the canonical can point at a URL that no longer exists. Historically Google didn’t even respect canonicals inserted with JavaScript; that’s loosened in some cases, but HTML-level canonicals remain far more reliable, and multiple conflicting tags just force Google to pick.

The fix: own canonical logic at the rendering layer (the framework), not inside the CMS, and build absolute URLs from a single SITE_URL environment variable. One source of truth, absolute URLs always, never relative.

Locale ownership: API fallback vs. frontend routing

Multi-locale headless sites have a version of the same ownership confusion as canonicals. The content API’s locale selection and fallback can substitute field values — request a locale, get that locale’s content or a configured fallback — but that’s a data-substitution feature, not an SEO feature. Evidence for this claim Content API locale selection and fallback can substitute field values, but the frontend still owns locale URLs, canonicals, hreflang, x-default, and language negotiation. Scope: Contentful localization docs plus Google rendering/canonical guidance. Confidence: high · Verified: 2026-07-18 Contentful: Localization Google: JavaScript SEO basics The frontend still owns every search-facing piece:

• Locale URLs. Whether locale lives in a path (/es/page), a subdomain, or a separate domain is a routing decision the frontend makes — the API doesn’t generate URLs.
• Canonical per locale. Each locale version gets its own canonical pointing at itself, not all pointing back at the default locale.
• hreflang and x-default. Build the full set of alternate-language links from the frontend’s known locale routes, including an x-default for unmatched languages — the API has no concept of hreflang.
• Content-negotiation and status behavior. Decide deliberately what happens when a locale is requested that doesn’t exist for a given entry: redirectA redirect sends browsers and crawlers from a requested URL to a different one. An HTTP redirect specifically is a 3xx status code paired with a Location header; meta refresh and JavaScript redirects achieve a similar navigation without being a 3xx response themselves. Permanent redirects (301/308) are Google's signal the target should be canonical; temporary ones (302/303/307) aren't. to the default locale, serve the fallback content at that locale’s URL, or return a real 404 — and stay consistent about which one, since Google treats “the API silently substituted English text” and “this locale variant doesn’t exist” as different situations that call for different HTTP status codes.

The practical trap: API-level fallback can make a missing translation look fine in the CMS preview (you always see content, never a blank field), which means locale gaps tend to surface first as SEO problems — wrong-language titles indexed under the wrong hreflangHreflang is an annotation (in HTML, HTTP headers, or XML sitemaps) that tells search engines which language and optional region a page targets, and which alternate versions exist. It only works when every page in the cluster references all the others., or duplicate contentThe same or very similar primary content reachable at more than one URL. There's no general duplicate content penalty — the real costs are possible signal dilution, the wrong URL getting chosen, and less-efficient crawling. across locales that never triggered an editorial alert.

Sitemaps and robots.txt

No Yoast means no automatic sitemap. Build it programmatically: Next.js App Router generates /sitemap.xml from a sitemap.ts file (querying the CMS at build or request time); Nuxt has sitemap modules; Gatsby has gatsby-plugin-sitemap; Astro has @astrojs/sitemap. The trap on high-publish-volume sites is build-time static sitemaps that go stale — use ISR-regenerated sitemaps segmented by content type.

Robots.txt likewise has to be explicit — a static file in /public or a generated route (robots.ts in Next.js). The one rule you cannot get wrong: never disallow .js or .css. Blocking them prevents rendering entirely.

Keeping it in sync with publishing

Cache and revalidation are an editorial-correctness problem, not just a performance one — time-, tag-, or path-based invalidation can serve stale content by design, so a publish action needs to reach every layer that cached a copy, not just the CMS. Evidence for this claim Time-, tag-, and path-based cache invalidation can serve stale content by design, so publish, unpublish, rename, and locale changes need webhook-triggered purge and rollback handling, not a fixed timer. Scope: Next.js current cache/revalidation model. Confidence: high · Verified: 2026-07-18 Next.js: Revalidating Before launch, write down what happens to each of these on four events — publish, unpublish, rename/slug change, and locale update — and test it:

• API/CDN cache for that entry.
• Framework page cache (ISR/on-demand revalidation, tag- or path-based).
• CDN edge cache in front of the frontend.
• Sitemap — the entry added, removed, or re-listed under a new URL.
• Metadata — old canonical/URL fully retired, not left resolving alongside the new one.
• Rollback — if a publish gets reverted, confirm the purge runs in reverse too, not just forward.

The trigger should be a webhook from the CMS’s publish/unpublish event calling your framework’s tag- or path-based revalidation (revalidateTag, revalidatePath, or the equivalent), not a fixed timer — a timer means every one of those four events waits for the next cycle instead of updating immediately.

Internal links and structured data

Internal linksAn internal link is a hyperlink from one page on a website to another page on the same website. Internal links help search engines discover your pages and pass ranking signals (PageRank and anchor-text context) between them. have to be real <a href> tags. A <div onClick> or <span> that navigates via JavaScript is not crawlable — Googlebot only follows real anchors. And JS-rendered links aren’t discovered until the render wave, which adds delay. API-driven content doesn’t produce link structures on its own, so related-posts, breadcrumb, and in-content link surfaces all have to be wired up at the component level.

Structured dataStructured data is a standardized way of labeling page content (using the schema.org vocabulary in JSON-LD, Microdata, or RDFa) so search engines can understand its meaning. It's not a direct ranking factor — its value is rich results and entity understanding. is the rare place headless is easier than WordPress: JSON-LD goes straight into a server-rendered <head> with zero client-bundle cost, it’s version-controlled in code, and there are no plugin conflicts. The usual types for content sites — Article/BlogPosting, BreadcrumbList, FAQPage, Organization — all apply. Test with the Rich ResultsRich results (formerly 'rich snippets') are enhanced search listings — stars, images, prices, breadcrumbs, video thumbnails, and more — that Google and Bing build from structured data. They're a display feature, not a ranking factor, and eligibility never guarantees they'll show. Test after any rendering change, since JS-injection timing can affect what the test sees.

Preview and staging environments

Headless stacks generate preview and branch-deploy URLs (Vercel/Netlify preview deployments, CMS draft endpoints) that are frequently publicly reachable. If Google indexes them, it sees a full duplicate of your site on another host. The fixes: apply a noindex HTTP header at the host level (in the environment config — not just a meta tag a CSR page might inject late), gate previews behind signed tokens, set environment-aware canonicals so staging never self-canonicalizes, and use short-lived preview hosts. Watch Search ConsoleGoogle's free tool for monitoring crawling, indexing, and search performance. for unexpected domains showing up — that’s your early warning.

Get the order of defenses right, because it’s easy to reach for noindex first and stop there. noindex only works if Google is allowed to crawl the page and see the tag — it’s a request about indexing, not an access control, so it does nothing against a determined crawler or a leaked link if the page itself is publicly reachable. Evidence for this claim A noindex rule is not access control and requires Google to crawl the page to see it; private headless previews should be authenticated first, with noindex as a secondary indexing safeguard. Scope: Google noindex documentation plus Contentful/Sanity preview-token separation as representative platform evidence. Confidence: high · Verified: 2026-07-18 Google: Block Search indexing with noindex Sanity: Presenting and previewing content The real boundary has to sit further upstream:

1. Authentication first. Preview environments should require a signed token or login before serving anything — noindex is a secondary safeguard for the rare page that has to stay reachable, not the primary control.
2. Separate tokens and hosts per environment. Preview and production should never share an API token or a hostname; preview’s token is the one that’s allowed to see unpublished content, and it should never end up in a production build.
3. Query the right content perspective. Production code queries published-only content; only the preview environment queries the draft/preview perspective. Get this backwards and production can leak unpublished entries even with authentication and noindex both in place.

TIP Compare matched preview and production pages before release

A preview environment should differ where access and noindex controls are intentional, but metadata, canonicals, hreflang, schema, and normalized content should not drift by accident. Browser rendering is optional and may be reported as not evaluated.

Run the release check with my free Staging vs. Production SEO Diff Free

1. Pair the same route on staging and production before the frontend release.
2. Separate intentional staging protections from accidental content, directive, or canonical differences.
3. Fix the rendering or environment configuration and rerun the exact pair before launch.

Tap to enlarge

The comparison reports that the canonical is different: staging points to staging.example/page while production points to www.example/page.

Bing and IndexNow

BingbotBingbot is Microsoft Bing's primary web crawler — the bot that discovers, fetches, and renders pages to build the Bing index. That index also powers Yahoo, DuckDuckGo, Ecosia, and Microsoft Copilot, so Bingbot's reach is far wider than Bing's own search-market share. now renders JavaScript using Microsoft Edge (Chromium) — the same web platform technology as Googlebot — but it does so less consistently than Google. Screaming Frog’s testing found Bing’s JS indexing “far from reliable,” with their blunt conclusion: “if you care about SEO and sleeping at night, don’t rely on client-side rendering.” So SSR/SSG matters even more if Bing traffic counts.

Bing also leans hard on a push model. Because headless content updates flow through an API and don’t ping Bing the way a WordPress plugin would, IndexNowIndexNow is an open push protocol that lets you instantly tell participating search engines (Bing, Yandex, Naver, Seznam, and Yep) which URLs you've added, changed, or removed via a simple HTTP request — and one submission is shared across all of them. Google does not use it. is especially valuable here — wire an IndexNow trigger to your CMS publish webhook so changed URLs get signaled instantly. Fabrice Canel’s crawl-economy framing is worth keeping in mind: fewer, cleaner URLs are better, so don’t let API-driven faceted navigation spawn thousands of uncanonicalized parameter URLs.

Migrating to headless without tanking traffic

Migrations are where headless SEO actually goes wrong. By industry analysis, WordPress-to-headless migrations frequently see large traffic drops and long recoveries — treat figures like a ~50% drop and a ~523-day recovery as a directional warning about how badly a botched migration hurts, not as precise numbers. The root causes are predictable: broken 301s (especially on category, tag, and paginated archive pages everyone forgets), metadata that didn’t carry over, and a rendering mode that silently defaulted to CSR. Inventory every URL (not just posts), build a complete 301 map before go-live, verify metadata and canonicals on the new frontend, do a Screaming Frog crawl comparison pre/post, resubmit sitemaps to both GSC and Bing Webmaster Tools, and stand up IndexNow. See the migration checklist tab for the full list.

Related reading lives in the JavaScript SEOMaking sure search engines can crawl, render, and index content that depends on JavaScript. and rendering topics — headless SEO is really a specialized application of both.

AI summary

A condensed take on the Advanced version:

• Architecture is the product. The CMSA content management system (CMS) is software that lets users create, manage, and publish digital content — like blog posts and pages — without writing raw code. WordPress, Drupal, and Joomla are the most common open-source CMS platforms. backend is nearly SEO-neutral; the frontend’s renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. mode decides everything. “Headless is bad for SEO” is a myth.
• Ownership map: CMS content model = raw structured fields. Delivery API = published-only content for production. Preview/management API = draft content, on its own tokenA token is the smallest unit of text (or image/audio/video) an LLM processes — roughly 4 characters, or about ¾ of an English word. A context window is the maximum number of tokens (input plus output) a model can hold at once, like its short-term memory./host. Frontend/build = the actual rendered <head>, canonical, sitemapA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing., robots.txtA plain-text file at the root of a host that tells crawlers which URLs they may and may not request. It controls crawling, not indexing — a blocked URL can still be indexed if it's linked from elsewhere., schema, and locale routing. Production must never call the preview/management API or token.
• RenderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. modes: SSG and SSR ship fully-rendered HTML and are the safe picks. CSR is the riskiest (content only exists after a later render wave). ISR is a good middle ground but has a trap.
• The ISR trap: after the revalidation window, the next request — possibly GooglebotGooglebot is Google's web crawler — the software that fetches pages so Google can index and rank them. It comes in two variants, Googlebot Smartphone (primary, under mobile-first indexing) and Googlebot Desktop, and runs an evergreen Chromium renderer. — still gets the stale page; the fresh one serves only on the following request. Use SSR for volatile data.
• Dynamic rendering is deprecated — Google now recommends SSR, static rendering, or hydrationActivating server-rendered HTML in the browser by attaching JavaScript handlers.. It’s not automatically cloaking, but don’t use it on new builds.
• AI-crawlerA crawler — also called a spider or bot — is an automated program that fetches web pages, extracts their links, and queues new URLs to visit. Search engines use crawlers to discover and download content for their index. rendering is provider-specific — CSR pages depend on client execution that is not covered by one shared contract. SSR/SSG maximizes coverage.
• Rebuild what the plugin did: SEO fields in the content model → mapped into the <head> → sitemapA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing. + robots.txtA plain-text file at the root of a host that tells crawlers which URLs they may and may not request. It controls crawling, not indexing — a blocked URL can still be indexed if it's linked from elsewhere. built explicitly. Never block .js/.css. HTML-level metadata beats JS-injected. Define a fallback chain and escape rich-text fields before they hit a <title> or JSON-LDJSON-LD (JavaScript Object Notation for Linked Data) is a script-based structured data format, typically paired with the schema.org vocabulary to describe page content for search engines and AI systems. Google recommends it over Microdata and RDFa because it's the easiest format to implement and maintain at scale — but all three work, and structured data isn't a ranking signal. string.
• Canonicals fragment across CMS slug → framework URL → component tag. Set them at the rendering layer using absolute URLs from a single SITE_URL.
• Locale ownership splits the same way: the API’s locale fallback substitutes content, but the frontend owns locale URLs, per-locale canonicals, hreflang, x-default, and what happens when a translation is missing.
• Links must be real <a href> — <div onClick> isn’t crawlable.
• Preview defense in order: authenticate first, keep preview/production tokens and hosts separate, query published-only content in production — noindex is a secondary safeguard, not access control, since Google has to crawl the page to see the tag.
• Publish/unpublish/rename/locale changes need a webhook-triggered purge across API cache, framework cache, CDN, sitemap, and metadata — not a fixed timer — plus a rollback path.
• Bing renders JS (via Edge) but less reliably than Google; use IndexNowIndexNow is an open push protocol that lets you instantly tell participating search engines (Bing, Yandex, Naver, Seznam, and Yep) which URLs you've added, changed, or removed via a simple HTTP request — and one submission is shared across all of them. Google does not use it. on the CMS publish webhook. Google enforces a ~2 MB resource cap.
• Migrations fail on broken 301s, lost metadata, and accidental CSR — full URL inventory + redirectA redirect sends browsers and crawlers from a requested URL to a different one. An HTTP redirect specifically is a 3xx status code paired with a Location header; meta refresh and JavaScript redirects achieve a similar navigation without being a 3xx response themselves. Permanent redirects (301/308) are Google's signal the target should be canonical; temporary ones (302/303/307) aren't. map before go-live.

Official documentation

Primary-source documentation from the search engines.

Google

• Understand JavaScript SEO Basics — the crawl → render → indexStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed. pipeline, canonicals with JS, soft 404sA soft 404 is a URL that returns a success status code (usually 200 OK) even though the page is empty, missing, or shows a 'not found' message. It isn't a status code a server sends — it's a label search engines apply after comparing the response code against the rendered content, and they treat the page like a 404 for indexing. in SPAs, and the History API guidance.
• Dynamic Rendering (deprecated workaround) — why Google deprecated it and what to use instead (SSR, static renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM., hydrationActivating server-rendered HTML in the browser by attaching JavaScript handlers.).
• Fix Search-Related JavaScript Problems — diagnosing rendered-DOM issues, stateless renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM., and fingerprinting against aggressive cachingCaching stores a copy of a page or resource — in a browser, a CDN edge node, or a search crawler's own cache — so it can be served again without regenerating or re-downloading it. It isn't a direct ranking factor, but it feeds page speed and crawl efficiency..
• Rendering for Content-Driven Web Apps — SSR vs. SSG vs. CSR tradeoffs for content sites.
• Rendering on the Web (web.dev — Addy Osmani & Jason Miller) — the canonical definitions of SSR, CSR, and hydration, plus the recommendation to prefer SSR or static rendering over full rehydration.

Bing / Microsoft

• The new evergreen Bingbot (Microsoft Edge) — BingbotBingbot is Microsoft Bing's primary web crawler — the bot that discovers, fetches, and renders pages to build the Bing index. That index also powers Yahoo, DuckDuckGo, Ecosia, and Microsoft Copilot, so Bingbot's reach is far wider than Bing's own search-market share. rendering JavaScript via the same web platform technology as GooglebotGooglebot is Google's web crawler — the software that fetches pages so Google can index and rank them. It comes in two variants, Googlebot Smartphone (primary, under mobile-first indexing) and Googlebot Desktop, and runs an evergreen Chromium renderer..
• IndexNow / indexnow.org — the push protocol to wire to your CMSA content management system (CMS) is software that lets users create, manage, and publish digital content — like blog posts and pages — without writing raw code. WordPress, Drupal, and Joomla are the most common open-source CMS platforms. publish webhook.

Quotes from the source

On-the-record statements from Google and Bing. Each link is a deep link that jumps to the quoted passage on the source page.

Google — how JavaScript pages are processed

• “All pages returning a 200 HTTP status codeAn HTTP status code is the three-digit number a server returns with every response to tell a browser or crawler what happened to its request — success, redirect, client error, or server error. For SEO the code matters as much as the content: it tells Google and Bing whether to index a page, follow a redirect, retry later, or drop the URL from the index. are queued for renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM., no matter whether JavaScript is present on the page.” — Google Search Central docs. Jump to quote
• “Google Search won’t render JavaScriptMaking sure search engines can crawl, render, and index content that depends on JavaScript. from blocked files or on blocked pages.” — Google Search Central docs. Jump to quote
• “Don’t use fragments to load different page content.” (use the History API instead) — Google Search Central docs. Jump to quote

Google — dynamic renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. is deprecated

• “Dynamic rendering was a workaround and not a long-term solution for problems with JavaScript-generated content in search engines.” — Google Search Central docs. Jump to quote
• Recommended instead: “server-side rendering, static rendering, or hydrationActivating server-rendered HTML in the browser by attaching JavaScript handlers..” — Google Search Central docs. Jump to quote
• “…creates additional complexities and resource requirements.” — Google Search Central docs. Jump to quote

Google — prefer SSR / static rendering (web.dev)

• “We encourage developers to consider server-side rendering or static rendering over a full rehydration approach.” — Addy Osmani & Jason Miller, web.dev. Jump to quote

Two checklists: headless SEO health + migration

Headless SEO health check

• Pages render their content in HTML on first request (SSR or SSG), not only after client-side JavaScript runs.
• No critical page depends on CSR for its main content (remember: AI crawlersAI crawlers are bots from AI companies that fetch web pages to train language models, build AI-search indexes, or answer live user questions. They come in three categories, each with its own user-agent tokens and its own robots.txt controls. don’t run JS).
• SEO fields (title, description, robots, canonical, OG) exist in the CMSA content management system (CMS) is software that lets users create, manage, and publish digital content — like blog posts and pages — without writing raw code. WordPress, Drupal, and Joomla are the most common open-source CMS platforms. content model and are mapped into the <head>.
• Canonicals are absolute URLs built from a single SITE_URL, set at the renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. layer — and they’re per-page, not a shared homepage canonical.
• robots.txt exists and does not block .js or .css.
• A sitemapA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing. is generated programmatically and stays fresh (ISR-regenerated / segmented on high-volume sites).
• Internal linksAn internal link is a hyperlink from one page on a website to another page on the same website. Internal links help search engines discover your pages and pass ranking signals (PageRank and anchor-text context) between them. are real <a href> tags — no <div onClick> navigation.
• Structured dataStructured data is a standardized way of labeling page content (using the schema.org vocabulary in JSON-LD, Microdata, or RDFa) so search engines can understand its meaning. It's not a direct ranking factor — its value is rich results and entity understanding. (JSON-LDJSON-LD (JavaScript Object Notation for Linked Data) is a script-based structured data format, typically paired with the schema.org vocabulary to describe page content for search engines and AI systems. Google recommends it over Microdata and RDFa because it's the easiest format to implement and maintain at scale — but all three work, and structured data isn't a ranking signal.) is in the server-rendered <head> and passes the Rich ResultsRich results (formerly 'rich snippets') are enhanced search listings — stars, images, prices, breadcrumbs, video thumbnails, and more — that Google and Bing build from structured data. They're a display feature, not a ranking factor, and eligibility never guarantees they'll show. Test.
• Preview/staging hosts return a host-level noindex header.
• IndexNowIndexNow is an open push protocol that lets you instantly tell participating search engines (Bing, Yandex, Naver, Seznam, and Yep) which URLs you've added, changed, or removed via a simple HTTP request — and one submission is shared across all of them. Google does not use it. fires on the CMS publish event (for Bing and others).

Migration checklist (traditional CMS → headless)

• Full URL inventory — not just posts: author pages, tag pages, paginated archives, parameter URLs.
• 301 redirectA 301 redirect is the HTTP status code for a permanent move: it tells browsers and search engines a URL has moved for good, and it's the strongest signal for consolidating a page's ranking signals onto the new URL. Google says permanent redirects don't cause a loss in PageRank. map for every changed URL, built before go-live.
• Metadata (title, description) migrated and verified per URL.
• Canonical tagsA rel=\"canonical\" annotation — in the HTML <head> or an HTTP Link header — that tells search engines which URL is the preferred version of duplicate or near-duplicate content. verified on the new frontend.
• RenderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. mode confirmed as SSR/SSG (not an accidental CSR default).
• SitemapsA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing. resubmitted to Google Search ConsoleA free Google service that reports how a site performs in Google Search and surfaces problems with how Google crawls, indexes, and serves it. It's first-party data straight from Google — but you don't need it to appear in results. and Bing Webmaster ToolsMicrosoft's free portal for monitoring and improving how a site appears in Bing search — the peer to Google Search Console, plus IndexNow instant indexing, richer backlink data, and keyword volumes. Because Bing's index also feeds Microsoft Copilot, it doubles as a window into AI-search visibility..
• Crawl comparison (Screaming Frog) run pre- vs. post-launch.
• Search ConsoleGoogle's free tool for monitoring crawling, indexing, and search performance. property set up for any new domain/protocol.
• IndexNowIndexNow is an open push protocol that lets you instantly tell participating search engines (Bing, Yandex, Naver, Seznam, and Yep) which URLs you've added, changed, or removed via a simple HTTP request — and one submission is shared across all of them. Google does not use it. implemented.

The mental models

1. Architecture is the product. The CMSA content management system (CMS) is software that lets users create, manage, and publish digital content — like blog posts and pages — without writing raw code. WordPress, Drupal, and Joomla are the most common open-source CMS platforms. backend is nearly SEO-neutral. The frontend’s renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. mode is the product. Before debugging anything in a headless site, answer one question first: how is the frontend renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. this content? Almost every headless SEO problem resolves to that.

2. The rendering-mode decision rule. Pick by how often the content changes and how interactive it is:

• Mostly static content (blogs, docs, marketing) → SSG (rebuild or ISR on a timer).
• Frequently-changing content that must always be fresh (prices, stock) → SSR.
• Changes on the order of hours/days, want static speed → ISR (mind the stale-on-first-request trap).
• Highly interactive, behind a login, not meant to be indexedStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed. → CSR is acceptable.
• Public content you want ranked or cited by AIAn AI citation is the visible source link an AI answer engine shows next to its generated text — the clickable reference that credits the web page it used. A citation's presence is a separate thing from whether the cited page actually supports the statement, and from being retrieved (read behind the scenes) or merely mentioned (named without a link); citation is driven more by brand mentions and being retrievable than by traditional ranking. → never CSR.

3. “Rebuild what the plugin did.” Every automatic Yoast/Rank Math behavior is now a deliberate build step: metadata fields in the content model → mapped to <head> → sitemapA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing. → robots.txtA plain-text file at the root of a host that tells crawlers which URLs they may and may not request. It controls crawling, not indexing — a blocked URL can still be indexed if it's linked from elsewhere. → canonicals → structured dataStructured data is a standardized way of labeling page content (using the schema.org vocabulary in JSON-LD, Microdata, or RDFa) so search engines can understand its meaning. It's not a direct ranking factor — its value is rich results and entity understanding.. If something’s “missing,” it usually means a plugin behavior was never re-implemented.

4. One source of truth for URLs. Canonicals, sitemapA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing. entries, and internal linksAn internal link is a hyperlink from one page on a website to another page on the same website. Internal links help search engines discover your pages and pass ranking signals (PageRank and anchor-text context) between them. should all derive from a single SITE_URL and the framework’s routing — not from slugs hand-assembled in three different layers. One source of truth kills canonical fragmentation.

5. HTML-first, JS-second. Anything that matters for crawlingCrawling is how search engines use automated bots (like Googlebot and Bingbot) to discover URLs and download pages. A page has to be crawlable to be indexed, but crawling on its own isn't a ranking factor. and indexingStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed. — content, metadata, canonicals, internal linksAn internal link is a hyperlink from one page on a website to another page on the same website. Internal links help search engines discover your pages and pass ranking signals (PageRank and anchor-text context) between them., structured data — belongs in the server-rendered HTML. Treat JS-injected SEO signals as a fallback, not the plan, because they’re seen late by Google and not at all by most AI crawlersAI crawlers are bots from AI companies that fetch web pages to train language models, build AI-search indexes, or answer live user questions. They come in three categories, each with its own user-agent tokens and its own robots.txt controls..

Headless SEO — cheat sheet

RenderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. modes at a glance

Metadata management by framework

Fast rules

• Never disallow .js / .css in robots.txtA plain-text file at the root of a host that tells crawlers which URLs they may and may not request. It controls crawling, not indexing — a blocked URL can still be indexed if it's linked from elsewhere..
• Canonicals: absolute URLs from one SITE_URL, set at the renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. layer.
• In Next.js App Router, set metadataBase or relative canonicals break.
• Internal linksAn internal link is a hyperlink from one page on a website to another page on the same website. Internal links help search engines discover your pages and pass ranking signals (PageRank and anchor-text context) between them. = real <a href>. <div onClick> is invisible to crawlersA crawler — also called a spider or bot — is an automated program that fetches web pages, extracts their links, and queues new URLs to visit. Search engines use crawlers to discover and download content for their index..
• Preview/staging: host-level noindex header, not a late JS meta tag.
• Google resource cap: ~2 MB, truncated beyond.
• Dynamic rendering: deprecated — use SSR / static rendering / hydrationActivating server-rendered HTML in the browser by attaching JavaScript handlers..
• Most AI crawlersAI crawlers are bots from AI companies that fetch web pages to train language models, build AI-search indexes, or answer live user questions. They come in three categories, each with its own user-agent tokens and its own robots.txt controls.: no JavaScript → CSR content is invisible to them.
• Bing: renders JS (Edge) but less reliably; wire IndexNowIndexNow is an open push protocol that lets you instantly tell participating search engines (Bing, Yandex, Naver, Seznam, and Yep) which URLs you've added, changed, or removed via a simple HTTP request — and one submission is shared across all of them. Google does not use it. to publish events.

Audit the server-delivered response

Export representative frontend routes to urls.txt. This intentionally uses the raw response rather than a browser so missing server-rendered metadata cannot hide behind hydrationTurning HTML, CSS, and JavaScript into the final visual page and DOM.:

while IFS= read -r url; do
  html=$(mktemp)
  status=$(curl -sS -o "$html" -w '%{http_code}' "$url")
  title_count=$(grep -Eio '<title>[^<]*</title>' "$html" | wc -l | tr -d ' ')
  canonical_count=$(grep -Eio '<link[^>]+rel=["'"']canonical["'"'][^>]*>' "$html" | wc -l | tr -d ' ')
  jsonld_count=$(grep -Eio '<script[^>]+type=["'"']application/ld\+json["'"']' "$html" | wc -l | tr -d ' ')
  printf '%s\t%s\ttitles=%s\tcanonicals=%s\tjsonld=%s\n' "$status" "$url" "$title_count" "$canonical_count" "$jsonld_count"
  rm -f "$html"
done < urls.txt

Run a rendered comparison separately for routes that intentionally stream or load content later. Never put CMSA content management system (CMS) is software that lets users create, manage, and publish digital content — like blog posts and pages — without writing raw code. WordPress, Drupal, and Joomla are the most common open-source CMS platforms. preview tokensA token is the smallest unit of text (or image/audio/video) an LLM processes — roughly 4 characters, or about ¾ of an English word. A context window is the maximum number of tokens (input plus output) a model can hold at once, like its short-term memory. in the URL list.

Tools for diagnosing headless SEO

• URL InspectionA Google Search Console feature that reports how Google sees one specific URL on a property you own. By default it shows the last-indexed snapshot; a separate \"Test live URL\" mode fetches the current version. (Google Search ConsoleA free Google service that reports how a site performs in Google Search and surfaces problems with how Google crawls, indexes, and serves it. It's first-party data straight from Google — but you don't need it to appear in results.) — see how a single URL was crawled and rendered. The rendered HTML / screenshot tells you whether your content actually made it in — essential for catching CSR gaps.
• Rich ResultsRich results (formerly 'rich snippets') are enhanced search listings — stars, images, prices, breadcrumbs, video thumbnails, and more — that Google and Bing build from structured data. They're a display feature, not a ranking factor, and eligibility never guarantees they'll show. Test — confirm JSON-LDJSON-LD (JavaScript Object Notation for Linked Data) is a script-based structured data format, typically paired with the schema.org vocabulary to describe page content for search engines and AI systems. Google recommends it over Microdata and RDFa because it's the easiest format to implement and maintain at scale — but all three work, and structured data isn't a ranking signal. is present in the rendered output after any renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. change (JS-injection timing can change what’s detected).
• Screaming Frog SEO SpiderA crawler — also called a spider or bot — is an automated program that fetches web pages, extracts their links, and queues new URLs to visit. Search engines use crawlers to discover and download content for their index. — crawl with JavaScript renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. on/off to compare what’s in raw HTML vs. rendered HTML; build the pre/post crawl comparison for migrations.
• Ahrefs Site Audit — surfaces redirect chainsA → B → C instead of A → C. Each hop loses link equity and adds latency., broken canonicals, missing metadata, and indexability issues across the whole frontend.
• Bing Webmaster ToolsMicrosoft's free portal for monitoring and improving how a site appears in Bing search — the peer to Google Search Console, plus IndexNow instant indexing, richer backlink data, and keyword volumes. Because Bing's index also feeds Microsoft Copilot, it doubles as a window into AI-search visibility. — Bing’s rendering/indexingStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed. view, plus where IndexNowIndexNow is an open push protocol that lets you instantly tell participating search engines (Bing, Yandex, Naver, Seznam, and Yep) which URLs you've added, changed, or removed via a simple HTTP request — and one submission is shared across all of them. Google does not use it. submissions show up.

Mistakes I keep seeing on headless builds

Shipping the marketing site as a client-rendered SPA. A raw React or Vue frontend with no SSR/SSG layer is the single most common headless SEO mistake. Why it’s wrong: GooglebotGooglebot is Google's web crawler — the software that fetches pages so Google can index and rank them. It comes in two variants, Googlebot Smartphone (primary, under mobile-first indexing) and Googlebot Desktop, and runs an evergreen Chromium renderer. has to queue the page for a second render wave before your content exists to it, while AI providers publish different or incomplete renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. contracts. HTML-only fetchers see the empty shell. Do instead: pick a framework that ships fully-rendered HTML by default (Next.js, Nuxt, Astro, Gatsby) and use SSR or SSG for any page you want foundA 302 (\"Found\") is a temporary redirect: it forwards users to a new URL while telling search engines the original URL should stay in the index. It's a weak canonicalization signal, not the zero-equity dead end of SEO folklore..

Treating the CMSA content management system (CMS) is software that lets users create, manage, and publish digital content — like blog posts and pages — without writing raw code. WordPress, Drupal, and Joomla are the most common open-source CMS platforms.’s slug field as the canonical URLHow search engines pick one canonical URL among duplicates and consolidate signals onto it.. Developers often build the <link rel="canonical"> straight from whatever the CMS returns. Why it’s wrong: the canonical then fragments across CMS slug, framework routing, and component logic — a renamed slug or refactored route silently breaks it. Do instead: build canonicals at the renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. layer from one SITE_URL environment variable, never from CMS output directly.

Letting preview/staging deployments stay publicly crawlable. Vercel/Netlify preview URLs and CMS draft endpoints are reachable by default. Why it’s wrong: if Google finds one, it can indexStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed. a full duplicate of your site on another host — and a noindex meta tag injected late by JavaScript often isn’t enough to stop it. Do instead: apply noindex as an HTTP header at the host level, and gate previews behind signed tokensA token is the smallest unit of text (or image/audio/video) an LLM processes — roughly 4 characters, or about ¾ of an English word. A context window is the maximum number of tokens (input plus output) a model can hold at once, like its short-term memory..

Setting up ISR and assuming it’s always fresh. Teams pick ISR for the “good enough” freshness and stop thinking about it. Why it’s wrong: the request that triggers regeneration after the revalidation window — possibly GooglebotGooglebot is Google's web crawler — the software that fetches pages so Google can index and rank them. It comes in two variants, Googlebot Smartphone (primary, under mobile-first indexing) and Googlebot Desktop, and runs an evergreen Chromium renderer. — still gets served the stale cached page; only the next request sees the update. Do instead: use ISR for content that changes on the order of hours or days, and switch genuinely volatile data (prices, stock levels) to SSR instead.

Building navigation and related-content links as clickable <div>s. Component libraries make it easy to wire an onClick navigation handler onto any element. Why it’s wrong: search engines only follow real <a href> anchors — a <div onClick> is invisible to crawlersA crawler — also called a spider or bot — is an automated program that fetches web pages, extracts their links, and queues new URLs to visit. Search engines use crawlers to discover and download content for their index. no matter how it looks to a visitor. Do instead: render every internal linkAn internal link is a hyperlink from one page on a website to another page on the same website. Internal links help search engines discover your pages and pass ranking signals (PageRank and anchor-text context) between them., including related-posts and breadcrumb links pulled from the API, as an actual anchor tag.

Disallowing .js or .css in robots.txtA plain-text file at the root of a host that tells crawlers which URLs they may and may not request. It controls crawling, not indexing — a blocked URL can still be indexed if it's linked from elsewhere. “to save crawl budgetThe number of URLs an engine will crawl in a timeframe..” This shows up more than you’d expect on headless builds that inherited an old robots.txt. Why it’s wrong: Google can’t render a page whose JavaScript or CSS is blocked, so this doesn’t save crawl budget — it breaks rendering entirely. Do instead: leave .js and .css crawlable; there’s no legitimate reason to block them.

Symptom → cause → fix

URL Inspection shows the page fetched fine, but the rendered HTML is missing content

Cause: the page is client-side rendered and the content only exists after JavaScript runs in the browser — Google’s URL Inspection toolA Google Search Console feature that reports how Google sees one specific URL on a property you own. By default it shows the last-indexed snapshot; a separate \"Test live URL\" mode fetches the current version. shows you the post-render DOM, and if your main content is still missing there, the render wave isn’t producing it (or hasn’t run yet). Fix: confirm the renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. mode with Patrick’s Render Gap tool, which compares raw HTML against rendered HTML for a URL. If the gap is real, move that route to SSR or SSG rather than relying on client-side fetches.

The canonical Google reports in Search Console isn’t the one in your code

Cause: canonical fragmentation — the CMSA content management system (CMS) is software that lets users create, manage, and publish digital content — like blog posts and pages — without writing raw code. WordPress, Drupal, and Joomla are the most common open-source CMS platforms. slug, the framework’s URL assembly, and the component that renders the tag have drifted out of sync, or a shared layout is emitting the same canonical on every page. Fix: check the live tag with Patrick’s Canonical Checker, then move canonical construction to the renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. layer and build it from one SITE_URL variable instead of three separate pieces.

Traffic dropped sharply right after a headless migration

Cause: almost always broken 301s — especially on category, tag, and paginated archive pages nobody remembered to map — or metadata that didn’t carry over from the old CMS. Fix: run every old URL through Patrick’s Redirect Checker to confirm each one resolves with a single 301 to the correct destination, not a chain or a 404, then verify titles and descriptions migrated per URL.

Preview or staging URLs are turning up in Search Console or a site: search

Cause: the preview/staging host was never blocked from indexingStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed. at the host level — a meta-tag noindex injected client-side can arrive too late for Google to see it. Fix: apply the noindex HTTP header in the environment config itself (not just page markup), and gate the preview host behind a signed tokenA token is the smallest unit of text (or image/audio/video) an LLM processes — roughly 4 characters, or about ¾ of an English word. A context window is the maximum number of tokens (input plus output) a model can hold at once, like its short-term memory. so it isn’t publicly crawlable at all.

The Rich Results Test doesn’t detect structured data that’s clearly in your source code

Cause: the JSON-LDJSON-LD (JavaScript Object Notation for Linked Data) is a script-based structured data format, typically paired with the schema.org vocabulary to describe page content for search engines and AI systems. Google recommends it over Microdata and RDFa because it's the easiest format to implement and maintain at scale — but all three work, and structured data isn't a ranking signal. is being injected client-side after the initial HTML response, and the timing doesn’t line up with what the test — or GooglebotGooglebot is Google's web crawler — the software that fetches pages so Google can index and rank them. It comes in two variants, Googlebot Smartphone (primary, under mobile-first indexing) and Googlebot Desktop, and runs an evergreen Chromium renderer.’s first pass — actually sees. Fix: move the JSON-LDJSON-LD (JavaScript Object Notation for Linked Data) is a script-based structured data format, typically paired with the schema.org vocabulary to describe page content for search engines and AI systems. Google recommends it over Microdata and RDFa because it's the easiest format to implement and maintain at scale — but all three work, and structured data isn't a ranking signal. into the server-rendered <head>, then re-check with Patrick’s Schema Validator or the Rich Result Eligibility Checker against the raw response, not just the browser-rendered DOM.

The sitemap still lists URLs you deleted or renamed months ago

Cause: a build-time static sitemapA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing. that only regenerates when the whole site rebuilds — on a high-publish-volume site, that can be days or weeks out of date. Fix: switch to a sitemapA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing. that regenerates on the same cadence as your content (ISR-regenerated or segmented by content type), and confirm the current output with Patrick’s Sitemap Validator.

Which rendering mode should this page use?

The renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM.-mode choice is the one decision that determines almost everything else about a headless page’s SEO. Work through it per route, not once for the whole site — a marketing site and its authenticated dashboard routes can (and should) land in different places.

Traffic dropped after a headless migration — the next moves

This is the scenario I see most often, and it has a predictable set of root causes. Work the list in order — each step either fixes the problem or rules it out and sends you to the next one.

1. Pull the crawl statsA Google Search Console report (under Settings) that shows how Google has crawled your site over the last 90 days — total requests, download size, and average response time, broken down by response code, file type, Googlebot type, and purpose. It's only available for root-level properties (a Domain property or a URL-prefix property verified at the site's root). and coverage report in Search ConsoleA free Google service that reports how a site performs in Google Search and surfaces problems with how Google crawls, indexes, and serves it. It's first-party data straight from Google — but you don't need it to appear in results. first. If you see a spike in 404s or a drop in indexedStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed. pages right after launch, go to step 2. If indexingStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed. looks stable but rankings/traffic still dropped, skip to step 5.
2. Check for broken redirectsA redirect sends browsers and crawlers from a requested URL to a different one. An HTTP redirect specifically is a 3xx status code paired with a Location header; meta refresh and JavaScript redirects achieve a similar navigation without being a 3xx response themselves. Permanent redirects (301/308) are Google's signal the target should be canonical; temporary ones (302/303/307) aren't.. Run your full pre-migration URL list — not just posts, but author pages, tag pages, and paginated archives — through Patrick’s Redirect Checker. If any resolve to a 404, a redirect chainA → B → C instead of A → C. Each hop loses link equity and adds latency., or the wrong destination, build (or fix) the 301 map before doing anything else.
3. If redirects are clean, check metadata migration. Spot-check titles and descriptions on your highest-traffic pre-migration URLs against what’s live now. Metadata that didn’t carry over from the old CMSA content management system (CMS) is software that lets users create, manage, and publish digital content — like blog posts and pages — without writing raw code. WordPress, Drupal, and Joomla are the most common open-source CMS platforms. is the second most common cause of a post-migration drop.
4. If metadata is fine, check the renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. mode. Confirm the new frontend didn’t silently default to CSR — use Patrick’s Render Gap tool on a sample of pages to compare raw vs. rendered HTML. A framework misconfiguration that drops SSR/SSG to CSR is exactly the kind of thing that ships without anyone noticing.
5. If all of the above check out, verify canonicals didn’t fragment. Spot check with the Canonical Checker — a shared layout canonical or a slug that changed during migration can quietly consolidate rankings onto the wrong URL.
6. Resubmit sitemapsA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing. to both Google Search ConsoleA free Google service that reports how a site performs in Google Search and surfaces problems with how Google crawls, indexes, and serves it. It's first-party data straight from Google — but you don't need it to appear in results. and Bing WebmasterMicrosoft's free portal for monitoring and improving how a site appears in Bing search — the peer to Google Search Console, plus IndexNow instant indexing, richer backlink data, and keyword volumes. Because Bing's index also feeds Microsoft Copilot, it doubles as a window into AI-search visibility. Tools, and confirm IndexNowIndexNow is an open push protocol that lets you instantly tell participating search engines (Bing, Yandex, Naver, Seznam, and Yep) which URLs you've added, changed, or removed via a simple HTTP request — and one submission is shared across all of them. Google does not use it. is wired to your CMS’s publish webhook so new and changed URLs get signaled going forward rather than waiting to be recrawled.
7. If you’ve worked through steps 2–6 and traffic still hasn’t recovered, treat it as a longer recovery, not a bug to hunt down — headless migrations that fix all the technical issues still typically take real time to fully recover, since Google has to re-crawl and re-evaluate the new site structure.

Prompts for headless SEO tasks

These are meant to be pasted into whatever AI assistant you’re using, with the bracketed input swapped in. They’re scoped to the specific tasks this article covers — not generic “audit my SEO” prompts.

1. Spot CSR-only content in a page component

Paste your page/template component (e.g. a Next.js page.tsx or a Nuxt .vue file) and ask:

Here is a page component from my headless CMS frontend. Identify any content
that is fetched or rendered only on the client (inside useEffect, onMounted,
or similar client-only hooks) rather than during server rendering or build.
For each one, tell me whether it would be present in the initial HTML
response or only appear after JavaScript runs in the browser.

[paste component code]

Expect back a list of specific content blocks flagged as server-rendered vs. client-only, which tells you exactly what won’t be visible to AI crawlersAI crawlers are bots from AI companies that fetch web pages to train language models, build AI-search indexes, or answer live user questions. They come in three categories, each with its own user-agent tokens and its own robots.txt controls. or Google’s first-pass fetch.

2. Review a canonical-URL implementation for fragmentation risk

Paste the code that builds your canonical tagA rel=\"canonical\" annotation — in the HTML <head> or an HTTP Link header — that tells search engines which URL is the preferred version of duplicate or near-duplicate content. (the CMSA content management system (CMS) is software that lets users create, manage, and publish digital content — like blog posts and pages — without writing raw code. WordPress, Drupal, and Joomla are the most common open-source CMS platforms. field, the URL assembly logic, and the component that renders <link rel="canonical">) and ask:

This is how my headless site builds its canonical URL across three layers:
the CMS content model, the framework's URL assembly, and the rendering
component. Identify any point where these could drift out of sync (a slug
change, a route change, a hardcoded fallback) and suggest how to consolidate
this into a single source of truth built from one SITE_URL variable.

[paste canonical-related code from CMS field, framework logic, and component]

Expect back specific drift risks tied to your actual code, not generic canonical advice.

3. Draft the SEO fields to add to a CMS content model

Describe your content types and ask:

I'm setting up SEO fields in a headless CMS content model for [content type,
e.g. "blog post" / "product page"]. List the fields I should add (title,
description, robots override, canonical override, Open Graph fields, etc.),
a sensible field type for each, and which ones should have sensible
auto-generated defaults vs. requiring manual entry.

[describe your content type and any existing fields]

Expect back a field-by-field list you can hand to whoever configures the CMS, scoped to the content type you described rather than a generic checklist.

4. Compare raw vs. rendered HTML for a migration crawl

Paste two crawl exports (raw HTML crawl and JS-rendered crawl, e.g. from Screaming Frog run both ways) and ask:

Here are two crawl exports of the same URL set from my headless site — one
crawled with JavaScript rendering off (raw HTML) and one with it on
(rendered HTML). Compare them and flag any URLs where the title, meta
description, canonical, or main content differs meaningfully between the two,
since that gap indicates content is only appearing after client-side
rendering.

[paste or summarize the two exports]

Expect back a list of URLs where raw and rendered HTML diverge — those are your CSR-dependent pages worth fixing first.

Resources worth your time

My related writing

• JavaScript SEO Issues & Best Practices — my primary reference on the renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. side of all this; directly relevant to headless. Covers renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. modes, metadata modules (Meta tagsMeta tags are HTML elements in a page's head that pass metadata about the page to search engines and browsers. For SEO only a few matter — the title element, the meta description, and the robots meta tag — while meta keywords and most others are ignored., Helmet, Head), JS canonicals, sitemapsA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing., and the robots.txtA plain-text file at the root of a host that tells crawlers which URLs they may and may not request. It controls crawling, not indexing — a blocked URL can still be indexed if it's linked from elsewhere. Allow: .js / Allow: .css rule.
• The Beginner’s Guide to Technical SEO — where rendering and crawlingCrawling is how search engines use automated bots (like Googlebot and Bingbot) to discover URLs and download pages. A page has to be crawlable to be indexed, but crawling on its own isn't a ranking factor. fit in the bigger picture.

My speaking

• JavaScript SEO — Ungagged 2019 (SlideShare) — my walkthrough of how headless/decoupled CMSes separate frontend from backend, plus GooglebotGooglebot is Google's web crawler — the software that fetches pages so Google can index and rank them. It comes in two variants, Googlebot Smartphone (primary, under mobile-first indexing) and Googlebot Desktop, and runs an evergreen Chromium renderer.’s stateless rendering behavior. (Standing disclaimer: the dynamic-rendering recommendation in that deck is now outdated — Google deprecated it.)

From others

• Rendering on the Web (web.dev) — Addy Osmani & Jason Miller’s definitive rendering-modes piece.
• Bing JavaScript rendering study (Screaming Frog) — the reality check on how consistently Bing actually indexes JS.
• Client-Side vs. Server-Side Rendering (Search Engine Journal) — Martin Splitt on why Google renders all HTML.
• No-JavaScript Fallbacks in 2026: Less Critical, Still Necessary (Search Engine Land, James Allen) — covers AI crawlersAI crawlers are bots from AI companies that fetch web pages to train language models, build AI-search indexes, or answer live user questions. They come in three categories, each with its own user-agent tokens and its own robots.txt controls. not executing JS and the 2MB Google resource cap; sourced Vercel’s finding that none of the major AI crawlersA crawler — also called a spider or bot — is an automated program that fetches web pages, extracts their links, and queues new URLs to visit. Search engines use crawlers to discover and download content for their index. render client-side content.
• Architecture Decisions That Affect Rankings (Focus Reactive) — one of the more rigorous independent pieces on how specific headless architecture choices ripple into SEO outcomes.
• Beginner’s Guide to Headless CMS (Oncrawl, Dan Taylor) — a technical SEOTechnical SEO is the practice of making a site easy for search engines to crawl, render, index, and (now) be eligible for AI answers. It's the foundation that lets your content and links rank — not a ranking trick of its own.-first walkthrough of the decoupled architecture and its crawlingCrawling is how search engines use automated bots (like Googlebot and Bingbot) to discover URLs and download pages. A page has to be crawlable to be indexed, but crawling on its own isn't a ranking factor. implications.
• SEO Essentials for Headless Commerce (Women in Tech SEO, Safia Marmon) — practical implementation guide for headless e-commerce SEO; covers metadata, canonicals, and sitemapA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing. patterns.
• Next.js Metadata & OG Images (Next.js docs) — official reference for generateMetadata, metadataBase, and the App Router head-management patterns covered in the Advanced tab.
• r/TechSEO — the community for rendering/indexingStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed. debugging.

Headless CMS SEO

A headless CMS decouples content storage and editing (the backend) from how that content is rendered and delivered (the frontend), serving content over an API instead of a built-in templated 'head'. Its SEO outcomes come almost entirely from how the separate frontend renders pages.

Related: JavaScript SEO, Rendering

Headless CMS SEO

A headless CMSA content management system that separates the content repository from the presentation layer, delivering content via API to any front-end framework rather than rendering HTML server-side itself. It doesn't specify the rendering mode, hosting, cache, preview security, or publishing workflow — those are separate decisions. is a content management system whose backend — content storage, the editing UI, and the content model — is fully decoupled from the frontend that renders and presents that content. Instead of binding content to a templated theme the way WordPress or Drupal do, a headless CMSA content management system (CMS) is software that lets users create, manage, and publish digital content — like blog posts and pages — without writing raw code. WordPress, Drupal, and Joomla are the most common open-source CMS platforms. stores content once and serves it over an API (REST or GraphQL) to any client: a website, a mobile app, a smart display. The word “headless” means there’s no built-in “head,” no HTML presentation layer; you build or choose a separate frontend (Next.js, Nuxt, Gatsby, Astro, SvelteKit, and so on) that fetches content via the API and handles renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM..

A decoupled CMS is a close relative — it ships with an optional built-in frontend but can also serve content via API to an external one. True headless platforms (Contentful, Sanity, Prismic, Hygraph, Contentstack, Strapi) have no native frontend at all.

For SEO, the key thing to understand is that the CMS backend itself has almost no direct impact. What matters is how the frontend turns API-delivered content into HTML that crawlersA crawler — also called a spider or bot — is an automated program that fetches web pages, extracts their links, and queues new URLs to visit. Search engines use crawlers to discover and download content for their index. can read — the renderingTurning HTML, CSS, and JavaScript into the final visual page and DOM. strategy (SSG, SSR, ISR, or CSR), the discipline around metadata, canonicals, sitemapsA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing., and internal linksAn internal link is a hyperlink from one page on a website to another page on the same website. Internal links help search engines discover your pages and pass ranking signals (PageRank and anchor-text context) between them., and operational practices like keeping preview environments out of the indexStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed.. “Headless is bad for SEO” is a myth; headless is neutral, and your implementation decides the outcome.

Related: JavaScript SEO, Rendering

Changelog