Headless CMS SEO

I start with a rendering audit. Every public page that needs search traffic must be server-rendered or statically rendered. I have seen too many headless sites rely on client-side rendering for indexable pages, then wonder why rankings tank. Here is a concrete example: a client with 10,000 product pages was using CSR through a React framework. Their [Core Web Vitals](/core-web-vitals/) LCP hovered around 4.2 seconds, and only 70% of pages were indexed after three months. We switched to static site generation with incremental static regeneration. LCP dropped to 1.1 seconds, and indexation hit 98% within a week. My decision rule is simple: if you have more than 5,000 pages or any page that must rank, use SSG or SSR. For smaller sites, SSR on demand works, but be careful with server costs.

Next, I define SEO fields directly in the content model. I create a 'page' content type with required fields for meta title, meta description, slug, canonical URL, and a noindex toggle. I also add a JSON-LD structured data field where editors can paste or build [schema markup](/schema-markup/). This ensures every piece of content has the metadata it needs before it is published. Without this, you end up with inconsistent tags that require manual fixes later. I also set up a fallback in the frontend: if the meta title field is empty, it defaults to the page title. That is a safety net, not a crutch.

[Canonical tags](/canonical-tags/) are non-negotiable. In a headless setup, the same content can appear on multiple URLs through different API calls, query parameters, or channel distribution. I pull the canonical URL from a CMS field or generate it automatically from the primary route. The frontend template inserts a <link rel="canonical"> element. This one step prevents most duplicate-content headaches. I also generate XML sitemaps dynamically from the CMS API on each build. I use a serverless function that calls the content API, lists all public pages, and outputs a sitemap.xml. This exposes new pages to crawlers faster than a static file that updates once a day.

Client-side rendering for public pages is the biggest trap. Some teams argue that Google can handle JavaScript now, and technically it can, but the reality is unreliable. I tested a headless news site where 30% of articles were not indexed after six months because the content was only available via client-rendered JavaScript. After switching to SSR, indexation rose to 98% within a week. The decision rule: if a page is meant to be found through search, it must be server-rendered or pre-rendered. Hybrid rendering is an option — CSR for dashboards or logged-in areas, SSR for all public content — but never mix on the same page.

Missing canonical tags is another silent killer. In a headless architecture, the same content can be served on multiple URLs because the frontend may generate different paths based on API responses, session parameters, or A/B test variants. Without a [canonical tag](/canonical-tag/), you create [duplicate content](/duplicate-content/) that confuses search engines and dilutes link equity. I once inherited a site where every product page existed at three URLs: /product/123, /product/123?colour=red, and /product/123?size=m. The canonical tags were missing, so the site had 30,000 URLs competing for the same content. Implementing canonicals sorted it out.

Inconsistent metadata happens when SEO fields are optional or missing from the content model. Editors forget to fill them, and the frontend has to guess. I have seen default titles like "Untitled" appear in search results. The fix is to make all SEO fields required in the CMS and add validation. Also watch for performance pitfalls: heavy JavaScript bundles, unoptimised images, and lack of CDN caching can undo your SSR gains. I always run a Lighthouse audit before launch and monitor Core Web Vitals after. Finally, rendering errors with ISR can occur if revalidation times are too long or if the cache is stale. Set a sensible revalidate period, such as 60 seconds for news and 1 hour for evergreen content, and test that pages update correctly.

I used to think headless CMS SEO was just about adding meta tags. That was naive. The real bottleneck is the rendering layer. I once launched a headless site using a popular JavaScript framework with CSR. The meta tags were perfect, the structured data was in place, the sitemap was submitted — but pages were not being indexed. I spent weeks debugging, assuming the problem was in the content model or the robots.txt file. It was not until I checked the rendered HTML in Google's URL Inspection Tool that I realised the search engine was seeing an empty shell. The content was only loaded after JavaScript executed. Switching to SSR fixed it overnight. That mistake cost me two months of lost organic traffic.

I also underestimated the importance of canonical tags in headless setups. In a traditional CMS, the CMS often handles canonical URLs automatically. In a headless architecture, the same piece of content can be fetched by different frontend routes or served on multiple domains. I had a case where a client's blog posts were being duplicated across /blog/ and /news/ because the API returned the same entries for both endpoints. Without canonical tags, search engines saw double content. I now set canonical tags as a required field in every content type and enforce it with frontend logic.

Another thing I got wrong was sitemap generation. I used to think a static sitemap that I rebuilt once a day was sufficient. But in a headless setup, content is published from the CMS and a rebuild may not trigger automatically if the sitemap is a separate static file. I changed my mind and now generate sitemaps dynamically using the CMS API during each build, and I also offer a real-time sitemap endpoint for the latest content. This ensures new pages appear in sitemaps within minutes, not hours. Lastly, I learned the hard way that structured data should be built into the content model from the start. Retroactively adding schema markup is messy and error-prone. I now include a JSON-LD field in every content type and provide a template for editors.