Single-page React apps have a well-known SEO problem. A crawler that doesn’t execute JavaScript hits your site and sees this:<\/p>\n\n\n\n
<div id=\"root\"><\/div>\n<\/code><\/pre>\n\n\n\nNothing else. No title, no description, no content. Everything a search engine or a link-unfurling bot cares about only exists after React mounts, runs its components, and renders into that div. Some crawlers do execute JS now, but not reliably, not consistently, and not for every route on your site with the same timing guarantees. If SEO matters to you, you can’t leave that to chance.<\/p>\n\n\n\n
I ran into this directly while working on my portfolio site, guicoder.com. Here’s the two-part fix: react-helmet-async to manage per-route metadata, and a custom Puppeteer prerendering script to bake that metadata into static HTML at build time.<\/p>\n\n\n\n
Part one: per-route metadata with react-helmet-async<\/h2>\n\n\n\n
By default, a React SPA has one <title><\/code> and one set of meta tags defined once in public\/index.html<\/code>. Every route shares them. That’s a problem if you want each page to describe itself accurately: your resume page and your samples page shouldn’t have identical titles and descriptions.<\/p>\n\n\n\nreact-helmet-async solves this by letting each route declare its own head content as part of its component tree. A page component might render something like:<\/p>\n\n\n\n
<Seo\n title=\"Samples | Guicoder\"\n description=\"A collection of accessible React components and applications.\"\n canonical=\"https:\/\/guicoder.com\/samples\"\n\/>\n<\/code><\/pre>\n\n\n\nInternally, that component uses react-helmet-async<\/code>‘s <Helmet><\/code> to inject the title, description, canonical link, and Open Graph tags into <head><\/code> at runtime. Navigate to a different route, and the tags update to match.<\/p>\n\n\n\nThis is a real improvement, but it only exists after JavaScript runs. It’s a runtime fix. If a crawler doesn’t execute your JS, or gives up before helmet’s effect fires, none of it matters.<\/p>\n\n\n\n
Part two: capturing the rendered output with Puppeteer<\/h2>\n\n\n\n
This is where prerendering comes in. The idea: instead of hoping a crawler will run your JS correctly, run it yourself, once, at build time, and save the result as static HTML.<\/p>\n\n\n\n
The rough shape of the process:<\/p>\n\n\n\n
\n- Build the app normally.<\/li>\n\n\n\n
- Spin up a local static server serving the build output.<\/li>\n\n\n\n
- Launch a headless browser (Puppeteer) and visit each route.<\/li>\n\n\n\n
- Wait for React to mount and helmet to inject its tags.<\/li>\n\n\n\n
- Grab the fully-rendered HTML from the page.<\/li>\n\n\n\n
- Write that HTML to disk at the matching route path.<\/li>\n<\/ol>\n\n\n\n
The result is a set of static files like build\/samples\/index.html<\/code>, build\/resume\/index.html<\/code>, each containing the correct title, description, canonical URL, and OG tags for that specific route, already present in the markup a crawler receives on first load. Once the page’s own JS kicks in, React hydrates over that markup and the app behaves like a normal SPA from there.<\/p>\n\n\n\nThe part that’s easy to get wrong: timing<\/h2>\n\n\n\n
The tricky detail is step 4. React mounting and helmet committing its tags don’t happen instantly, and they don’t happen in lockstep with typical “page ready” signals like Puppeteer’s networkidle0<\/code>. If you snapshot too early, you capture the DOM before helmet has written anything route-specific, and every one of your prerendered pages ends up with the same default metadata baked in. That defeats the entire point.<\/p>\n\n\n\nThe fix is to wait for a specific, verifiable signal rather than a generic timeout. Checking for any<\/em> non-empty meta description tag isn’t reliable if a static default value already exists in your HTML template; that check can pass before the route-specific value ever loads. A more precise approach is to wait for the canonical link tag to match the exact URL expected for that route:<\/p>\n\n\n\nawait page.waitForFunction(\n (expectedPath) => {\n const canonical = document.querySelector('link[rel=\"canonical\"]');\n return !!canonical && canonical.href.endsWith(expectedPath);\n },\n {timeout: 10000},\n route,\n);\n<\/code><\/pre>\n\n\n\nThis only proceeds once the canonical tag actually reflects the current route, which means helmet has committed its changes and the snapshot will be accurate. Only after that check passes does the script call page.content()<\/code> and write the file.<\/p>\n\n\n\nWhy not just use an existing tool<\/h2>\n\n\n\n
Tools like react-snap package this whole workflow, using Puppeteer under the hood with generic heuristics for detecting when a page is ready. They work fine for simple cases, but the heuristics aren’t aware of your app’s specific rendering pipeline or of exactly when helmet commits its changes. That mismatch is precisely the class of bug described above, and it’s easier to introduce than to catch. Writing the prerender script by hand costs more upfront, but it means the “is this page actually ready” check is built around something you control and can verify directly, rather than a guess made by a generic tool.<\/p>\n\n\n\n
The result<\/h2>\n\n\n\n
Two pieces working together solve the problem neither solves alone:<\/p>\n\n\n\n
\n- react-helmet-async<\/strong> gives each route control over its own metadata at runtime.<\/li>\n\n\n\n
- Puppeteer prerendering<\/strong> captures that metadata into static HTML at build time, so it’s present before any JavaScript runs.<\/li>\n<\/ul>\n\n\n\n
A crawler hitting any route on the site now gets a complete, accurate <head><\/code> on the very first response. No JS execution required, no waiting, no guessing.<\/p>\n","protected":false},"excerpt":{"rendered":"Single-page React apps have a well-known SEO problem. A crawler that doesn’t execute JavaScript hits your site and sees this: Nothing else. No title, no description, no content. Everything a search engine or a link-unfurling bot cares about only exists after React mounts, runs its components, and renders into that div. Some crawlers do execute […]<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[5],"tags":[],"class_list":["post-72","post","type-post","status-publish","format-standard","hentry","category-web-performance-seo"],"_links":{"self":[{"href":"https:\/\/www.guicoder.com\/blog\/wp-json\/wp\/v2\/posts\/72","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.guicoder.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.guicoder.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.guicoder.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/www.guicoder.com\/blog\/wp-json\/wp\/v2\/comments?post=72"}],"version-history":[{"count":1,"href":"https:\/\/www.guicoder.com\/blog\/wp-json\/wp\/v2\/posts\/72\/revisions"}],"predecessor-version":[{"id":73,"href":"https:\/\/www.guicoder.com\/blog\/wp-json\/wp\/v2\/posts\/72\/revisions\/73"}],"wp:attachment":[{"href":"https:\/\/www.guicoder.com\/blog\/wp-json\/wp\/v2\/media?parent=72"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.guicoder.com\/blog\/wp-json\/wp\/v2\/categories?post=72"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.guicoder.com\/blog\/wp-json\/wp\/v2\/tags?post=72"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}