Prerendering 280 pages of a React SPA for SEO: what actually worked

Hayley Henning — Wed, 22 Jul 2026 14:26:55 +0000

We shipped a Vite + React single page app with about 280 routes: marketing pages, a blog, and a batch of programmatically generated county pages. All client rendered. The problem is not users, it is crawlers and share cards. A raw SPA serves the same index.html for every route, so anything that does not execute JavaScript sees an identical, empty shell no matter which URL it requested. This post walks through the actual prerender pipeline we run after every build, what it gets right, what it does not, and the two gotchas that cost us the most time. The site is virdix.co if you want to see the output in practice.

Why we did not just switch to a meta framework

The obvious answer is "use Next.js" or "use Remix." We did not, for a boring reason: the app was already a mature Vite SPA with its own routing (wouter), its own build pipeline, and no server. Rewriting the framework to get SSR would have meant rewriting the app. What we actually needed was much narrower: crawlers and social scrapers need to see the right title, meta description, Open Graph tags, and JSON-LD for each URL. Real users, who run JavaScript, do not need any of that baked in, they get it from a React effect the moment the page mounts.

So the fix is a post-build script, not a framework migration.

The pipeline

After vite build produces dist/, a Node script does the following:

Spins up a tiny local HTTP server that serves dist/ as static files, falling back to the built index.html shell for any path that is not a real file (the same behavior the production host needs to provide for client side routing to work).
Launches headless Chromium via Puppeteer.
For every route in a list, opens a new page, navigates to it, and waits for two things: the app's root element to have children, and document.title to be non empty. That second check matters more than it sounds like it should.
Serializes document.documentElement.outerHTML and writes it to dist/<route>/index.html (or dist/index.html for the homepage, dist/404.html for the not found route).

The route list itself is generated, not hand maintained. Static marketing routes live in an array, but blog slugs and county page slugs are discovered by reading the actual data files in the repo (readdirSync over the county data directory, a regex over blog post metadata) so the prerender list can never silently drift out of sync with what the app actually renders.

Why "wait for title" instead of a fixed timeout

Early versions of this script used a flat waitForTimeout(2000) after navigation. It worked until it did not: on a slower CI runner, some pages had not finished mounting by the 2 second mark, so we wrote empty shells to disk for a handful of routes and did not notice until a Search Console coverage report flagged pages with no content.

The fix was to wait on an actual signal instead of a guess:

await page.waitForFunction(
  () => {
    const el = document.querySelector("#root");
    return el && el.children.length > 0 && document.title.length > 0;
  },
  { timeout: 45000 },
);

Per-page SEO in this app is set by a shared component that runs in a useEffect and sets document.title, meta tags, and injects a JSON-LD script tag. Waiting for the title to be non-empty is a reliable proxy for "this route's data has loaded and the SEO effect has run," because that effect is one of the last things to fire on mount. This also means the JSON-LD is not a separate step, it gets serialized into the static HTML for free as part of capturing the full DOM.

The gotcha nobody warns you about: animation libraries

We use framer-motion for entrance animations (fade and slide in on scroll or on mount). The first time we shipped prerendered pages, Lighthouse and actual users on a cold load saw a flash of invisible content: the serialized HTML captured elements mid animation, with inline opacity: 0 and a translate transform baked in, and it took a full client hydration for React to catch up and make them visible. That is a bad first paint for a page that is supposed to be pre-rendered specifically to look done immediately.

The fix runs right before serialization, inside the same Puppeteer page context:

await page.evaluate(() => {
  for (const el of document.querySelectorAll('[style*="opacity"]')) {
    if (el.style.opacity !== "" && parseFloat(el.style.opacity) < 1) {
      el.style.opacity = "1";
    }
    if (/^(translate|scale)/.test(el.style.transform)) {
      el.style.transform = "none";
    }
  }
});

This walks the DOM and forces any element caught in a partial animation state to its final, visible state before we serialize the HTML. On the client side, the animation library is told to skip the entrance animation specifically on prerendered boots, so React does not fight the static HTML by re-running the fade-in on top of already-visible content. Static output looks done. Client boot does not re-animate something that is already there.

Getting picked up faster: IndexNow

Prerendering solves what crawlers see once they show up. It does not make them show up sooner. For that we run a small script after every production deploy that pings the IndexNow API (used by Bing, Yandex, and a few other participating engines) with every URL currently in the sitemap:

const body = { host, key, keyLocation, urlList };
await fetch("https://api.indexnow.org/indexnow", {
  method: "POST",
  headers: { "Content-Type": "application/json; charset=utf-8" },
  body: JSON.stringify(body),
});

The key is a token published as a text file at the site root, which is how IndexNow verifies you actually control the domain before it will act on your submission. A 200 or 202 response means it accepted the batch, 202 specifically means the key has not been validated by every participating engine yet, which is normal on the first run. This does not touch Google, which does not participate in IndexNow, but for the engines that do, new and changed county pages get queued for a crawl right after deploy instead of waiting for the next scheduled pass.

What this approach does not do

Worth being honest about the limits. This is a build time snapshot, not real SSR: if data changes between deploys, the static HTML is stale until the next build and prerender run. It also does not help with anything that depends on request time context (auth state, geolocation, A/B tests), because there is no server making per-request decisions, just static files. For a marketing site and a blog with mostly stable content, that tradeoff is fine. For an app with per-user server rendered state, it would not be.

The whole thing is a few hundred lines of Node and Puppeteer, no framework rewrite, no server to run in production. If you are stuck with a client rendered SPA and cannot justify migrating it to get SSR, this is the pragmatic middle ground.