← all packages SP

SPA.js

Turns a page into a persistent, full-viewport frame that quietly stays in sync with the real document — title, favicon, background, and the address bar itself — so navigating between pages on the same origin feels continuous, without a client-side router.

same-origin only no network interception ~2.9 KB min

Live demo — simulated browser chrome

https://example.com/

Home

This box represents the top-level page. Click below to simulate an in-app navigation — watch the URL bar, tab title, and favicon update together, the way SPA.js syncs an iframe with its host.

how it works

Two small pieces, one message channel

SPA.js runs the same script on both sides of the frame boundary and figures out which role to play by checking whether it's already inside an iframe.

01Host page mounts a full-viewport iframe pointed at the original URL, then listens for postMessage updates.
02Framed page watches its own title, favicon, background, and history state via MutationObserver and reports changes up.
03Same-origin links update the outer URL with history.pushState, so back/forward and shareable URLs keep working.
04Cross-origin links are handed off to a real, visible navigation — nothing is masked or intercepted silently.

Usage

One script tag, no configuration. Add it once, at the end of <body>, on every page of the site.

<script src="https://cdn.jsdelivr.net/gh/AetherCodez/SPA.js/spa.min.js"></script>
<!-- that's it — no init call, no config object -->

Behavior	Detail
Sync target	Document title, favicon (`<link rel="icon">`), computed background color, and `location.href`.
Origin policy	Only same-origin navigations are absorbed into the frame; anything else triggers a normal top-level navigation.
Network	The script never proxies, intercepts, or rewrites network requests — it only relays DOM state via `postMessage`.
Fallback	A 500 ms poll backstops frameworks that mutate the URL in ways `pushState`/`popstate` hooks don't catch.