Skip to main content

SPA Detection Configuration

The [detect] section configures PRISM's automatic SPA (Single-Page Application) shell detection. When enabled, PRISM can analyze origin responses to determine whether a page is an SPA shell that needs rendering, rather than relying solely on route patterns.

TOML Example​

[detect]
auto = false
max_body_text_bytes = 500
min_script_tags = 2
mount_points = ["app", "root", "__next", "__nuxt"]
header = "X-Prism-Render"

Parameters​

ParameterTypeDefaultDescription
autoBooleanfalseEnable automatic SPA shell detection
max_body_text_bytesInteger500Maximum visible text bytes in <body> for a page to be considered an SPA shell
min_script_tagsInteger2Minimum number of <script> tags to qualify as an SPA shell
mount_pointsArray of Strings["app", "root", "__next", "__nuxt"]HTML element IDs that indicate a framework mount point
headerString"X-Prism-Render"Response header from origin to explicitly request rendering

Detailed Explanation​

auto​

Disabled by default. When enabled, PRISM inspects the origin's HTML response to determine if it is an SPA shell (minimal content that requires JavaScript execution). This is an opt-in feature because it adds a small overhead: PRISM must fetch and parse the origin response before deciding whether to render.

When disabled, PRISM relies on route patterns and bot detection to decide what to render.

SPA shell heuristics​

PRISM considers a page an SPA shell if all of the following are true:

  1. The <body> contains fewer than max_body_text_bytes of visible text (after stripping tags)
  2. The page has at least min_script_tags <script> tags
  3. The page contains a <div> with an id matching one of the mount_points

These heuristics reliably detect pages generated by React, Vue, Angular, Next.js, Nuxt, and similar frameworks.

max_body_text_bytes​

SPA shells typically have very little visible text -- just a loading spinner or empty <div> tags. The default threshold of 500 bytes catches most shells while avoiding false positives on server-rendered pages.

min_script_tags​

SPA shells load their application via <script> tags. Requiring at least 2 script tags (the framework runtime and the application bundle) reduces false positives from simple static pages that happen to have little content.

mount_points​

These are the id attributes of the root <div> where JavaScript frameworks mount their application:

  • app -- Vue.js default
  • root -- React default
  • __next -- Next.js
  • __nuxt -- Nuxt.js

Add custom mount point IDs if your application uses a different convention.

The origin application can explicitly request rendering by including this response header. When PRISM sees X-Prism-Render: true (or any truthy value) in the origin response, it renders the page regardless of other detection heuristics.

This provides a programmatic opt-in mechanism for your application to control rendering on a per-request basis.

Example Use Cases​

Enable auto-detection for a mixed-content site​

[detect]
auto = true
max_body_text_bytes = 300
min_script_tags = 2
mount_points = ["app", "root", "__next", "__nuxt"]

Custom framework mount point​

[detect]
auto = true
mount_points = ["app", "root", "__next", "__nuxt", "my-app-root"]

Header-only detection (no auto)​

[detect]
auto = false
header = "X-Prism-Render"

Your application adds X-Prism-Render: true to responses that need rendering, giving you precise per-route control without configuring route patterns.