A simple but powerful router module

• Code of Conduct
• Contributing
• Security Policy

[!CRITICAL] This package requires URLPattern to be polyfilled before any paths are registered. A common polyfill recommended by MDN can be found here.

npm install @aegisjsproject/router

You do not even need to npm install this or use any build process. You may either import it directly from a CDN or use an importmap.

<script type="importmap">
{
  "imports": {
    "@aegisjsproject/router": "https://unpkg.com/@aegisjsproject/router[@version]/router.mjs",
    "@aegisjsproject/state": "https://unpkg.com/@aegisjsproject/state[@version]/state.mjs"
  }
}
</script>

• Lightweight and Efficient: The library is designed to be small and performant, with a focus on efficient URL matching and module loading.
• Dynamic Loading: Modules are loaded on-demand, improving initial page load performance and reducing resource usage.
• Flexible Exports: Supports a variety of module exports, including custom elements, functions, and HTML structures, making it adaptable to different UI architectures.
• Component Injection: Automatically injects relevant URL information and state into registered components, simplifying component development and data management.
• History Integration: Seamlessly manages browser history, allowing users to navigate back and forward without reloading the entire page.
• Error Handling: Provides built-in error handling mechanisms to gracefully handle unexpected situations during module loading or navigation.
• Customizable: Offers flexibility for customization, allowing you to tailor the router's behavior to your specific project requirements.
• Easy to Use: The library provides a simple and intuitive API, making it easy to learn and integrate into your projects.

At its core, this package matches URLs matching a URLPattern to modules to be dynamically imported. This yields a powerful but minimal package size, dynamic loading of "View"s as-needed, high reusability of code, and potentially nearly instant navigations, especially when used in conjunction with service workers and caches. Just create a script that has a default export that is a Document, DocumentFragment, HTMLElement and especially a custom element or web component, and map the URLPatterns to their respective modules.

import { init, navigate, back, forward, reload } from '@aegisjsproject/router';

init({
  '/product/:productId': '@scope/views/product.js',
  '/test/': '@scope/views/home.js',
  '/search?q=:query': '@scope/views/search.js',
  '/img': '/views/img.js',
  '/path/page-:page(\\d+)': '@scope/foo.js',
}, {
  preload: true, // Preload all registered modules
  notFound: './views/404.js', // Set custom 404 module
  rootNode: '#root', // Declares element for base of content updates
  interceptRoot: document.body, // Use `MutationObserver` to observer `<a>` elements and intercept navigations
  signal: controller.signal, // An `AbortSignal`, should you want to disable routing funcitonality
});

document.querySelectorAll('[data-link]').forEach(el => {
  el.addEventListener('click', ({ currentTarget }) => {
    const { link, ...state } = currentTarget.dataset;
    navigate(link, state);
  });
});

document.querySelectorAll('[data-nav]').forEach(el => {
  el.addEventListener('click', ({ currentTarget }) => {
    switch (currentTarget.dataset.nav) {
      case 'back':
        back();
        break;

      case 'forward':
        forward();
        break;

      case 'reload':
        reload();

      default:
        throw new TypeError(`Invalid nav button type: ${currentTarget.dataset.nav}.`);
    }
  });
});

At the core, this router module just uses URLPatterns in a map, mapped to a source for a module. When a URL is navigated to, it finds the pattern that the URL matches, dynamically imports that module, and passes the current state and URL and the results of urlPattern.exec(url) to the function or constructor.

You may register paths via either registerPath() or through an object given to the init() function. registerPath() allows for the use of new URLPattern() to be used, but as init() requires an object, its keys must be strings to be converted into URLPattern through new URLPattern(key, moduleSrc).

If you call the init() function, the popstate listener will be added automatically and the module for the current page will be loaded. Should you want more manual loading, you may also call addListener() on your own.

There is also a MutationObserver that adds click event handlers to intercept clicks on same-origin <a>s. This observer watches for <a>s in the children of what it is set to observe and calls event.preventDefault() to avoid the default navigation, then calls navigate(a.href).

For all "Views"/modules that export a function or constructor, they are given an AbortSignal which is aborted on any navigation. This can and should be used for any necessary cleanup/freeing up memory, such as aborting any pending requests and removing event listeners.

You can register a module for 404 pages using either set404() or by passing it via { notFound } in init(). This component or function will be given the current state and URL and can be dynamically generated.

You can preload modules for views by using preloadModule() or by passing { preload: true } in init(). Preloading modules will make navigation effectively instant and potentially without network traffic, however it will increase initial load times (though it defaults to a low priority).

This currently uses @aegisjsproject/state for state mangement. It is a lightweight wrapper around history.state that uses BroadcastChannel to sync state changes between tabs/windows. It should be noted that this is global state and not specific to some component, so please avoid generic names and be aware of the global nature.