Owl Router 🦉

A lightweight SPA (Single Page Application) router based on the browser's History API. Zero dependencies, easy to use, and perfect for learning or small projects.

Installation

npm install @gio/owl-router

Basic Usage

import { createRouter } from '@gio/owl-router';

// Define your components (functions that return HTML or DOM elements)
const HomeComponent = () => '<h1>Home</h1><p>Welcome!</p>';
const AboutComponent = () => '<h1>About</h1><p>About us...</p>';

// Create the router
const router = createRouter({
  routes: [
    { path: '/', component: HomeComponent },
    { path: '/about', component: AboutComponent },
  ],
  container: '#app', // Element to render into (default: '#app')
  notFound: () => '<h1>404</h1><p>Page not found</p>' // Optional
});

// Start the router
router.start();

// Navigate programmatically
router.navigate('/about');

Loading External HTML Files

You can load external HTML files using the loadHTML helper:

import { createRouter, loadHTML } from '@gio/owl-router';

const router = createRouter({
  routes: [
    { path: '/', component: () => loadHTML('./pages/home.html') },
    { path: '/about', component: () => loadHTML('./pages/about.html') },
  ]
});

router.start();

API

createRouter(options)

Creates a router instance.

Options:

• routes: Array of { path: string, component: () => string | HTMLElement | Promise<string> }
• container: CSS selector or DOM element to render into (default: '#app')
• notFound: Component to display when route is not found (optional)

Returns:

• start(): Starts the router and renders the current route
• stop(): Stops the router and removes event listeners
• navigate(path): Navigates to a path
• getCurrentPath(): Returns the current path

loadHTML(filePath)

Loads an external HTML file and returns its content as a string.

Parameters:

• filePath: Path to the HTML file

Returns: Promise<string>

Features

• ✅ Zero dependencies
• ✅ Lightweight (~2KB)
• ✅ TypeScript support
• ✅ History API based
• ✅ Async component loading
• ✅ External HTML file support
• ✅ Custom 404 pages
• ✅ Programmatic navigation

Example

See the example.html file for a working example.

Purpose

This library was created for learning and experimentation with SPA routing using the History API.

Tests

npm test

License

MIT