Router

A lightweight client-side router with dynamic parameters, wildcard routes, grouped prefixes, middleware pipelines, navigation guards, and full browser history integration.

Quick Start

Register routes, add optional middleware, then call Aura.init() to start listening for URL changes.

import Aura from 'aurajs';

// Define routes
Aura.route('/', (ctx) => {
  console.log('Home page');
});

Aura.route('/users/:id', (ctx) => {
  console.log('User:', ctx.params.id);
});

// Add middleware
Aura.middleware((ctx) => {
  console.log('Navigating to', ctx.path);
  return true;
});

// Start the app
Aura.init();

Types

RouteContext

Every route handler and middleware receives a RouteContext object.

route() core

Register a route with a path pattern and a handler function. Supports dynamic segments (:param) and wildcard catch-all (/*).

// Static route
Aura.route('/about', (ctx) => {
  document.querySelector('#app').innerHTML = '<h1>About</h1>';
});

// Dynamic parameter
Aura.route('/posts/:slug', (ctx) => {
  console.log(ctx.params.slug);
});

// Named route
Aura.route('/users/:id', showUser, 'user-detail');

// Wildcard catch-all
Aura.route('/files/*', (ctx) => {
  console.log(ctx.params.wildcard); // everything after /files/
});

group() organization

Group multiple routes under a shared URL prefix. The callback receives a scoped router object with a route() method that automatically prepends the prefix.

Aura.group('/admin', (r) => {
  // Registers /admin/dashboard
  r.route('/dashboard', (ctx) => {
    console.log('Admin dashboard');
  });

  // Registers /admin/users/:id
  r.route('/users/:id', (ctx) => {
    console.log('Admin user', ctx.params.id);
  }, 'admin-user');
});

navigate() core

Programmatically navigate to a path. Pushes a new entry onto the browser history stack. Respects the beforeLeave guard and runs all registered middleware before executing the route handler.

// Navigate with history push
await Aura.navigate('/dashboard');

// Navigate with query params
await Aura.navigate('/search?q=aura&page=1');

redirect() core

Navigate to a path without pushing a new browser history entry. Useful for post-login redirects or replacing the current page silently.

// Redirect without adding to history
await Aura.redirect('/login');

middleware() guard

Register a global middleware function. Middleware runs in registration order before every route handler. Return true to continue or false to abort navigation (sets page state to 'error').

// Auth guard middleware
Aura.middleware((ctx) => {
  if (ctx.path.startsWith('/admin') && !isLoggedIn()) {
    Aura.redirect('/login');
    return false;
  }
  return true;
});

// Logging middleware
Aura.middleware((ctx) => {
  console.log(`[Router]`, ctx.path);
  return true;
});

beforeLeave() guard

Register a navigation guard that fires before leaving the current route. Only applies when using navigate(). Return false to cancel navigation (e.g. for unsaved-changes prompts).

Aura.beforeLeave((from, to) => {
  if (hasUnsavedChanges) {
    return confirm('Discard unsaved changes?');
  }
  return true;
});

errorPage() error

Register a handler for unmatched routes (404 pages). Called when no registered route pattern matches the requested path.

Aura.errorPage((ctx) => {
  document.querySelector('#app').innerHTML = `
    <h1>404</h1>
    <p>Page not found: ${ctx.path}</p>
  `;
});

refresh() core

Re-run the handler for the current route without changing the URL or pushing history. Useful after data updates when you need to re-render the current page.

This method takes no parameters.

// Re-execute the current route handler
await Aura.refresh();

urlFor() utility

Generate a URL string from a named route. Replaces :param placeholders with the provided values. Returns null if no route with the given name exists.

// Register a named route
Aura.route('/users/:id/posts/:postId', handler, 'user-post');

// Generate the URL
const url = Aura.urlFor('user-post', { id: '42', postId: '7' });
// => "/users/42/posts/7"

// Unknown name returns null
Aura.urlFor('nope'); // => null

back() utility

Navigate back one entry in the browser history. Equivalent to history.back().

This method takes no parameters.

Aura.back();

forward() utility

Navigate forward one entry in the browser history. Equivalent to history.forward().

This method takes no parameters.

Aura.forward();

pageState getter

Read-only getter returning the current page lifecycle state. The router automatically transitions through these states during navigation.

if (Aura.pageState === 'loading') {
  showSpinner();
}

currentPath getter

Read-only getter returning the full path (including query string) of the most recently handled route.

console.log(Aura.currentPath); // e.g. "/users/42?tab=posts"

navigationHistory getter

Read-only getter returning a copy of the internal navigation history array. Each entry records the path, extracted params, and a timestamp.

HistoryEntry

const history = Aura.navigationHistory;
console.log('Pages visited:', history.length);
console.log('Last page:', history[history.length - 1].path);

Emitted Events

The router emits the following events via the Aura event bus. Subscribe with Aura.on().

Aura.on('route:change', (ctx) => {
  console.log('Navigated to', ctx.path);
});

Aura.on('route:notFound', ({ path }) => {
  console.log('404:', path);
});