Aura Router

Keep the HTML. Upgrade the navigation.

HTML-first client navigation for complete static or server-rendered HTML pages – with nested layouts, route lifecycle hooks, and no framework adapter.

Your host keeps serving real pages. Aura adopts the HTML already on screen and upgrades marked links after load.

Try it: Live demo · Open in StackBlitz · Source · Article

npm install @auraui/router

10-minute tutorial · Quick start · Guide · Recipes · MAGA

Why Aura Router?

• Keep your pages. Every URL can return useful HTML before Aura runs.
• Add SPA navigation. Mark existing links and update only the view regions affected by the new route.
• Grow without a rewrite. Add nested layouts, lifecycle hooks, prefetching, and caching when you need them.

Works with plain HTML, Web Components, and Lit. Your backend or static host keeps rendering complete pages.

Design principles

Aura Router follows MAGA — and its discipline MANA (Minimal, Aligned, Native, Additive):

• Minimal — the smallest layer that upgrades navigation, not a second application model
• Aligned — ordinary <a href> stays a link; the URL stays a URL
• Native — URL, history, DOM, and HTML responses remain the substrate
• Additive — without JavaScript, marked links can still fall back to the server

MANA does not ban abstractions. It is how Aura judges them.

Vision and full essay: aura-ui/MAGA

How it works

1. The browser requests a normal URL.
2. Your host returns a complete HTML page.
3. Aura adopts the content already on screen.
4. Marked same-origin links use client navigation from then on.

MPA first. SPA when ready.

Quick start

For a complete two-page migration—including direct URLs, first-paint adoption, no-JavaScript fallback, and troubleshooting—follow Static site → SPA in 10 minutes.

1. Keep the page you already have

<main id="content">
  <h1>Home</h1>
</main>

Serve a complete page for every URL and keep the same selector around the content you want Aura to update.

2. Declare routes. Mark the links.

<a href="/about/" data-aura-link>About</a>

<aura-outlet></aura-outlet>
<aura-router extract="#content">
  <aura-route path="/" view="/"></aura-route>
  <aura-route path="/about/" view="/about/"></aura-route>
</aura-router>

extract tells Aura which region to take from each complete HTML response. On the first flat page, Aura adopts the matching region already on screen instead of fetching it again.

3. Start Aura once

import { AuraRouter } from '@auraui/router';

AuraRouter.install();

That is the upgrade: every URL still opens as a normal page, while marked links navigate through Aura after startup.

Change the page. Keep the layout.

Nested routes keep shared UI mounted while the child view changes – useful for dashboards, workspaces, and settings screens.

<aura-router extract="#content">
  <aura-route path="/workspace/" layout="workspace-shell">
    <aura-route path="." view="/workspace/"></aura-route>
    <aura-route path="settings" view="/workspace/settings/"></aura-route>
  </aura-route>
</aura-router>

<template id="workspace-shell">
  <nav><!-- durable chrome --></nav>
  <aura-outlet></aura-outlet>
</template>

Direct nested URLs need matching outlet-shaped HTML and an aura-router-ssr marker. See the nested layout recipe.

Add features when you need them

• Lifecycle hooks – guard, load, ready, leave, and unmount
• Prefetch and cache – configure link prefetch and route-scoped view, data, or DOM cache policies
• Authentication guards – protect client navigation without hiding server responsibilities
• First-paint adoption – reuse flat or nested HTML on startup
• 404 handling – keep client and server fallbacks honest
• Programmatic navigation – navigate from application code

Compatibility

Aura Router targets modern browsers with ES modules, Custom Elements, History API, and fetch. Parameterized routes require URLPattern.

It runs in the browser; it is not a Node SSR runtime. Your server or static host remains in control of the HTML response.

Project

Current release: 0.3.0

Documentation: Guide · Recipes · MAGA · Playground · Known limitations

Development: Changelog · Roadmap · Contributing · Security

Community: Article on DEV.to · GitHub Discussions · [email protected] · npm

License

MIT covers source code only – not the project name or logos. See LICENSE and TRADEMARKS.md.