Skip to content

Migration playbook

SPA to prerendered architecture

Moderate3 to 6 weeks

A 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. Prerendering serves static HTML snapshots to bots, keeping the SPA architecture intact for users.

Pre-flight

Before kickoff

  • Confirm the SPA is hitting real indexation problems (not just suspected ones) via Search Console URL Inspection.
  • Decide on managed (Prerender.io, Rendertron) vs self-hosted prerendering — see the build-vs-buy analysis.
  • 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.
  • Maintain prerender infrastructure even after rollback to avoid cold-start delays on re-enable.

Steps

Sequenced execution

  1. Step 1

    Set up prerendering infrastructure

    Deploy the prerender service (managed account or self-hosted cluster). Verify it can render a sample route correctly.

  2. Step 2

    Wire bot detection at edge or proxy

    Add user-agent based routing: verified bots (Googlebot, OAI-SearchBot, PerplexityBot, etc.) go to prerender; humans go to SPA origin. Use IP verification for compliance.

  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 TTLs and invalidation

    Set per-template cache TTLs based on freshness requirements. Wire invalidation hooks for content updates.

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.

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