> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abtestly.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Single-page apps
> How ABTestly works on apps with client-side routing, the lifecycle, the helpers, the gotchas, and the patterns that hold up in production.
If your site is built with **React, Vue, Next.js, Nuxt, SvelteKit, Astro**,
or any framework that swaps the page in JavaScript instead of doing a full
browser navigation, you have a single-page app (SPA). ABTestly supports
SPAs natively, the snippet watches for in-app route changes and re-runs
your experiments **without a page reload**.
This page is the **definitive reference**. It covers what to turn on, the
lifecycle, the three developer helpers (`onApply` / `onCleanup` / `waitFor`),
the canonical variant template, every common pitfall, and the guarantees we
make so your results stay trustworthy.
**TL;DR for impatient devs.** Turn on **SPA mode** in your site settings.
In a variant's **JavaScript** field, wrap your DOM work in
`abtestly.onApply(ABTESTLY_EXP_KEY, () => { ... })`. If you need to undo anything
(listeners, body classes, third-party widgets), pair it with
`abtestly.onCleanup(ABTESTLY_EXP_KEY, () => { ... })`. If the element you're editing
renders asynchronously, wrap the inside of `onApply` in
`abtestly.waitFor('.your-selector', (el) => { ... })`. The full canonical
template is just one click in the variant editor (**Insert SPA template**)
it's what most teams paste and adapt.
***
## 1. Enable SPA mode
SPA mode is a **per-site setting**. In your dashboard:
Sites → your site → **SPA** tab.
Toggling republishes your site config so the change reaches visitors
on the next pageview.
When SPA mode is **on**, the snippet:
* Wraps `history.pushState` and `history.replaceState`.
* Listens for `popstate` (back/forward) and `hashchange` (hash routers).
* Runs the [SPA lifecycle](#2-the-spa-lifecycle) on every detected
route change.
When SPA mode is **off** (the default), the snippet behaves exactly like
it does on a traditional multi-page site, **zero overhead, zero behavior
change**. There's no penalty for leaving it off on a non-SPA.
***
## 2. The SPA lifecycle
This is the single mental model the rest of the page builds on. Read it
once and the helpers below will make sense.
### Initial page load (any site)
1. The snippet boots, evaluates targeting and audiences for each experiment.
2. For every eligible experiment:
1. A bucket is computed (or read from cache if the visitor's been here).
2. An **impression beacon** fires.
3. The variant's **CSS** is injected into `` (tagged
`