Discussion starter: an ecommerce SEO question, posted with an answer from Niraj Raut to open the thread. If you have dealt with this on a site, reply with what you saw, especially where it differs.
- eCommerce SEO
- JavaScript SEO
Headless commerce migrations such as Hydrogen or custom React front ends: what went wrong for SEO that the platform demos never mention?
Disclosure: Niraj Raut, who posted this answer, runs the SEO consultancy linked at the end of it.
1 reply
-
adminAdmin
The risk people expect, that Google cannot read React, is the easiest one to rule out: Hydrogen renders on the server, custom React stacks can, Google renders JavaScript, and URL Inspection on a sample of each template shows what Google received. The damage the demos never show comes from quieter places: jobs the old storefront did that nobody wrote into the new specification, URL and status-code behaviour at the edges of the catalogue, and render or API dependencies that only break when Googlebot requests thousands of long-tail URLs that no demo ever loads.
Demos run on a small catalogue, one market, a fresh domain, warm caches and no third-party scripts. Your launch has legacy URLs with years of links, variants, discontinued products, several markets, a tag manager, and a crawler requesting pages nobody has viewed this month. Treat a headless build as a migration of every SEO behaviour the old storefront produced, and write each one into the acceptance criteria before launch.
The plumbing the old storefront handled for you
A Liquid theme or a monolithic platform produces a lot of SEO behaviour that is easy to leave out of a requirements document: canonical tags, sitemaps, robots.txt, redirects, pagination links, and status codes for missing products. A headless front end produces only what someone builds.
Shopify’s Hydrogen SEO guide covers a useful baseline: a
getSeoMetautility for meta tags and structured data, default sitemap routes that update within one day of pages being added or removed (the files are cached for 24 hours by default), and a default robots.txt route that, on Oxygen, is served only in the public production environment. The guide also calls itself “not a comprehensive guide to SEO best practices”. Redirects, alternate-language tags, pagination and status codes are not covered there; they sit elsewhere in the Hydrogen docs or in your own code. A custom React front end starts with none of it.Job Hydrogen starting point Custom React front end Launch check Titles, descriptions, canonicals getSeoMeta, with values supplied by your loadersBuild it One canonical per page, with the same value in the server HTML and after hydration XML sitemaps Default routes, updated within a day Build it Only 200, indexable, canonical URLs, for every market robots.txt Default route; on Oxygen, non-production deployments disallow all bots Build it Production serves the intended file; preview hosts are neither crawlable nor linked Legacy redirects storefrontRedirectlooks up redirects created in the Shopify adminBuild a lookup Every old URL with links or traffic returns one 301 to a 200 page Markets and alternate-language tags Your code and market setup Build it Reciprocal hreflang, correct locale codes, market URLs reachable without geo-redirects Product structured data Via getSeoMetaBuild it Rendered on the server from the same data as the visible price; every Offer carries a price, which merchant listings require Status codes Your loaders Build it 404 or 410 for products that are gone, 200 for out of stock, 503 when an upstream service fails Redirects and status codes: where migrations lose rankings
Headless lets you change URL patterns, and that quietly turns a front-end rebuild into a URL migration. Collection-scoped product paths, variant parameters, blog and page paths, and every URL with backlinks need a mapped destination. On Shopify, redirects saved in the admin do nothing for a custom front end unless you build a lookup. Hydrogen’s
storefrontRedirect“Queries the Storefront API to see if there is any redirect created for the current route and performs it”, and Shopify’s example calls it only after the app has returned a 404.That detail creates a specific failure. If a catch-all route answers an old URL with a 200 (an empty collection template, a friendly “not found” component, a search results page), the request never reaches the redirect lookup. The old URL lives on as a soft 404, and the links pointing at it stop doing anything useful.
Google’s JavaScript SEO basics explain why status codes matter beyond redirects: “All pages with a 200 HTTP status code are sent to the rendering queue”, while for non-200 pages “rendering might be skipped”. A server-rendered front end can return real status codes, so use them. Where a client-side route cannot, the same page offers two fallbacks: a JavaScript redirect to a URL that returns a 404, or a noindex robots meta tag added with JavaScript.
The quietest status-code failure comes from APIs. When the commerce API, the PIM or the search service times out, some front ends render an empty template with a 200 instead of an error. Google then sees a thin page rather than a temporary failure worth retrying. Return a 503 when an upstream dependency fails.
Links that work for shoppers but not for crawlers
The same Google page is direct: “Google can only discover your links if they are <a> HTML elements with an href attribute.” React makes it easy to break this without anyone noticing: product cards that navigate through a click handler, filters held in component state with no URL, and “load more” buttons with no linked page behind them.
Headless Shopify adds a platform-specific wrinkle. The Storefront API paginates with opaque cursors rather than page numbers. If those cursors end up in pagination URLs, page 2 of a collection gets a new URL whenever the products on page 1 change, and deep products lose a stable crawl path. Give paginated pages stable URLs (resolve
?page=3to a cursor on the server), and make sure deep products are also reachable through subcategory links.Head tags set in two places
Headless stacks can set head tags twice: once in the server HTML and again after hydration or client-side navigation. Google’s guidance is that the best way to set the canonical is in HTML, and that if JavaScript has to set it, you should “make sure that you always set the canonical URL to the same value as the original HTML”, with only one rel=”canonical” tag on the page. Look out for canonicals that carry variant, currency or tracking parameters, or that point at a preview host.
Robots directives have a sharper edge. When Google encounters a noindex, “it may skip rendering and JavaScript execution”, so a staging noindex left in the server HTML cannot be undone by client code. Check production response headers and raw HTML, not what the browser shows after hydration. Check the old storefront as well: a theme preview, the platform’s default domain or a legacy subdomain that stays publicly crawlable can compete with the new front end as a duplicate.
Failures that only appear at catalogue scale
A demo loads a handful of warm pages. Googlebot requests thousands of long-tail product, variant and collection URLs that no shopper opened recently, and each uncached request can mean a server render plus several API calls. Google’s crawl budget documentation explains that if a site slows down or responds with server errors, its crawl capacity limit goes down and Googlebot crawls less. After launch, watch the Crawl stats report for average response time, host status and server error responses, and compare cached with uncached response times in your own monitoring.
- Bot protection on your own APIs. Rate limits or challenges on search, pricing, review or PIM endpoints can hand Google’s renderer empty components. Check logs for verified Googlebot requests to those endpoints and their status codes.
- Serialised state in the HTML. Frameworks inline data for hydration. Googlebot fetches up to 2MB of an HTML file and ignores the rest, so pass only the fields a page renders.
- Stale bundles. Google’s JavaScript guidance notes that Googlebot “caches aggressively” and recommends content fingerprinting in filenames, which stops a new page rendering with last week’s JavaScript.
- Scripts the demo never had. Tag managers, review widgets, chat, personalisation and testing tools arrive after sign-off. Compare field data in the Core Web Vitals report before and after launch, on mobile.
- Crawlers that do not run JavaScript. Anything that exists only after hydration is invisible to them. Your logs show which bots request your JavaScript bundles and which never do.
Launch checks that catch these before Google does
- Crawl the live site and the staging build with the same settings. Diff status codes, titles, canonicals, meta robots, hreflang, structured data and internal links per template.
- Run every legacy URL with links or traffic through the new stack. Expect one 301 hop to a 200 page.
- Request deleted products, retired collections and invented paths. Expect a 404 or 410, not a 200 with a “not found” message.
- For each template, compare the raw server HTML with the rendered HTML from URL Inspection’s live test. The main content, links, canonical and JSON-LD should already be in the raw HTML.
- Load-test uncached long-tail URLs at crawl-like concurrency and record server response times.
- After launch, review daily for the first weeks: Googlebot status codes and response times in logs, the Page indexing report (“Page with redirect”, “Soft 404”, “Duplicate, Google chose different canonical than user”), Crawl stats, and Merchant Center diagnostics for landing page and price mismatches.
Hypothetical example:
A fashion retailer moves 9,000 products from a Liquid theme to a custom React front end on the same domain. The demo and user acceptance testing pass. At launch, collection-scoped product URLs that the old theme served now return 404, and redirects saved in the Shopify admin never fire because the new app has no lookup. The collection route is a catch-all that renders an empty grid with a 200 for any unknown handle, so 400 retired seasonal collections become soft 404s. Pagination uses cursor URLs, and uncached product pages take two to three seconds to render because each one calls three APIs. Over the following weeks, “Soft 404” rises in Page indexing, Crawl stats shows average response time climbing, and Googlebot requests fewer product pages. None of it would have shown in a demo.
What I would put in the contract
If I were signing off a headless launch, I would not accept “SEO-friendly framework” as a requirement. I would make the old site’s behaviour the specification: every URL’s status code and destination, every head tag, every crawlable link, and response times for uncached long-tail pages. The build passes when a crawl of staging matches that specification and a sample of uncached pages renders quickly under load, not when the demo looks fast.
Need help with this on your own site?
Niraj Raut works with businesses in Nepal, Australia, the UK, Europe and the US on technical SEO, ecommerce SEO, local SEO and AI search.
Add a reply Cancel reply
Replies are open to approved members. Log in or apply to join.