SPA section overlays

What this enables

A full-width SPA host overlay lets a section act as a wrapper for a deployed app. The section stays in the page order, keeps its section classes, styles, background, anchor id, and export behavior, but renders only the deployed raw_html snippet.

You can deploy any number of single page apps across multiple pages on the same site. Each app gets its own section deployment key, so a homepage calculator, a Shopify product finder, and a WordPress booking flow can all update independently and keep working after the pages export.

• Use this for React, Vue, Svelte, or plain JavaScript apps that should own the whole body of a page section.
• Use one overlay section per deployed SPA mount.
• Use different deployment keys for apps, environments, or placements that release independently. Reuse a key for placements that should update together.
• Each SPA host renders inside Bootstrap's .container by default; enable Make SPA full width when an app should render edge-to-edge.
• Host compiled JS, CSS, and assets on a public CDN or platform asset host, then deploy only the mount snippet to StaticPagesApi.

Create the host section

Create or edit a section and configure it as a pure SPA host.

• Set type_of to overlay.
• Set overlay_layout to full_width.
• Set full_width_content_position to spa_host.
• Leave Make SPA full width off when the app should sit inside .container, or turn it on for an edge-to-edge host.
• Set a section Deployment key such as homepage-calculator, shopify-product-finder, or wordpress-booking-flow.
• Deploy to the section key, not to a row key. In spa_host mode, child rows and native section content are not rendered.

{
  "type_of": "overlay",
  "overlay_layout": "full_width",
  "full_width_content_position": "spa_host",
  "spa_host_contained": "1",
  "deployment_key": "homepage-calculator",
  "section_classes": "min-vh-100"
}

Deploy the app snippet

Build the SPA in your frontend project, upload the compiled assets to a public host, then PATCH the section deployment key with the mount HTML.

• The raw_html payload should usually be one root element plus stylesheet and script tags.
• Use versioned asset URLs so rollbacks are simple.
• Keep secrets out of the snippet. Browser apps should call public APIs or authenticated APIs designed for the destination domain.
• After the deploy target updates, StaticPagesApi triggers the existing webhook publishing flow for pages that include the section.

curl -X PATCH "$STATIC_PAGES_API_URL/api/v1/component_deploy_targets/homepage-calculator" \
  -H "Authorization: Bearer $STATIC_PAGES_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "raw_html": "<div id=\"homepage-calculator-root\"></div><link rel=\"stylesheet\" href=\"https://cdn.example.com/apps/homepage-calculator.v12.css\"><script type=\"module\" src=\"https://cdn.example.com/apps/homepage-calculator.v12.js\"></script>"
  }'

Run many SPAs on many pages

Repeat the same pattern for each app placement. Give placements different keys when they deploy independently, or reuse one key when the same build should update every matching SPA host section atomically.

• One page can contain multiple SPA host overlays, such as a demo app section and a signup app section.
• Multiple pages can each host their own SPA overlays, such as a WordPress landing page, a Shopify product page, and a Rails account page.
• The same frontend repo can build several apps and deploy each output to a different key.
• The same compiled app can use one shared key when multiple pages should update to the same version together.
• Some app placements can use the default container while others are edge-to-edge; the choice lives on each SPA host section.

{
  "apps": [
    { "name": "calculator", "deployTargetKey": "homepage-calculator" },
    { "name": "booking", "deployTargetKey": "wordpress-booking-flow" },
    { "name": "finder", "deployTargetKey": "shopify-product-finder" }
  ]
}

Export to WordPress, Shopify, or another site

SPA host overlays are normal page sections in exported HTML. When a page exports to WordPress, Shopify, Rails, or another receiver, the section includes the deployed mount snippet and the browser loads the app assets from the URLs in that snippet.

This means a site can run several independent SPAs from the same StaticPagesApi organization without needing the receiving platform to know about the app source code.

• For body-only exports, make sure the receiving theme/layout allows script and link tags in the imported fragment or loads equivalent assets globally.
• Confirm destination CSP, CORS, and platform sanitization rules allow the app asset URLs.
• Use stable root element ids per app so multiple apps on one page do not fight over the same DOM node.
• Test the published destination page, not only the StaticPagesApi preview, because WordPress and Shopify themes can add their own CSS and script constraints.