Skip to content

Migration playbook

SPA to prerendered architecture migration

Moderate1 to 3 hours

A migration guide for teams running a React, Vue, or Svelte SPA where rewriting to SSR is too costly but crawlers (especially AI crawlers) cannot see the content. The ostr.io prerendering service renders, caches, and serves static HTML snapshots to bots, keeping the SPA architecture intact for users — the migration reduces to routing bot traffic to the service.

Pre-flight

Before kickoff

  • Confirm the SPA is hitting real indexation problems (not just suspected ones) via Search Console URL Inspection.
  • Create an ostr.io account, register your domain, and copy the Basic auth token from the integration guide — the service replaces any self-hosted rendering cluster.
  • Inventory routes that need prerendering vs routes that should remain SPA-only (auth-walled, etc.).
  • Verify that current canonical, OG, and JSON-LD logic works at first paint, not after JS hydration.
  • Plan bot-detection rules at the edge or at the origin proxy.

If things break

Rollback plan

  • Disable bot routing at the edge — bots fall back to SPA origin (slow but functional).
  • Keep bot detection toggleable per route family for partial rollback.
  • Keep the ostr.io account active even after rollback so re-enabling is a config flip, not a re-setup.

Steps

Sequenced execution

  1. Step 1

    Connect the ostr.io prerendering service

    No infrastructure to deploy — point a request at https://render.ostr.io/?url=<page URL> with your auth token and verify it renders a sample route correctly.

  2. Step 2

    Wire bot detection at edge or proxy

    Add user-agent based routing using a ready-made integration (Cloudflare Worker, Vercel middleware, AWS Lambda, or an Nginx/Apache rule): verified bots (Googlebot, OAI-SearchBot, PerplexityBot, etc.) go to the ostr.io renderer; humans go to SPA origin.

  3. Step 3

    Validate semantic parity

    Diff SPA-rendered content vs prerendered HTML. Visible content must match — different markup is fine, different meaning is cloaking.

  4. Step 4

    Roll out per route family

    Start with one route template (e.g., product pages). Verify Search Console picks up the new HTML over 7-14 days. Expand to more templates.

  5. Step 5

    Configure cache TTL and purging

    Set the cache TTL in the ostr.io dashboard to match content freshness requirements, and use the cache purge API or dashboard when content updates.

Expected metrics

Concrete expectations

Expected downtime
< 15 min (edge config flip)
Typical rollback time
< 5 min
Time to first verified indexation
14-28 days
Typical prerender cache hit ratio target
> 85%

After cutover

Monitoring discipline

  • Search Console Page indexing — expect indexation improvement within 14-28 days.
  • Crawler hit rate in server logs — segment by verified bot user-agent.
  • AI engine citation rate (manual sampling weekly) for branded and category queries.
  • Prerender cache hit ratio — should stabilize above 85% for healthy operation.
  • Origin load — bot traffic should be largely offloaded, freeing capacity.

FAQ

Common questions

Is prerendering for SPAs considered cloaking?

Not when implemented correctly. Compliant prerendering serves the same semantic content to bots and humans — only the delivery path differs (static snapshot vs JS render). Cloaking is when bots see materially different content. Match the rendered DOM between prerender output and runtime browser view to stay compliant.

Which bots should I route to the prerender?

At minimum: Googlebot, Bingbot, OAI-SearchBot, GPTBot, ClaudeBot, PerplexityBot, ChatGPT-User. Verify each via reverse DNS or published IP ranges to avoid impersonation. Avoid blanket User-Agent matching for non-bot traffic.

How long does prerendered HTML stay fresh?

Depends on content volatility. Editorial pages: 6-24 hours. Product/inventory: 5-30 minutes. Use shorter TTLs with on-publish cache invalidation triggered by your CMS. Set `stale-while-revalidate` so bots never wait for a cold render.

What if a page exists in the SPA but the prerender 404s?

Configure prerender to fall back to live SPA render with a 503 + Retry-After, never a 200 stub. Returning 200 for unrendered routes creates soft-404s that waste crawl budget.

Last updated:

Related deep-dives

Get this scoped to your stack

Generic playbooks are useful for orientation; the actual migration plan needs your routes, your CMS, your team capacity. The scoping call is 30 minutes — bring the constraints.

Book scoping callBrowse all migration guides

Other migration guides