README

This is the coolest web component router

More documentation coming up later

Eagrouter is an easy to use component router for web components. It works just like any other web component. It takes in 2 properties, a route configuration object and an optional route base string. Eagrouter is really a wrapper around Pagejs which is a tiny express-inspired client-side router; if you like pagejs, then you would like Eagrouter. It uses almost all the same api's for declaring routes as pagejs . It also uses rxjs for reactivity and LitElement. This three libraries combined together makes the router awseome to use.

Installation

npm install eagrouter

Usage

import "eagrouter";

Use as a normal html tag in your project root, and provide your route config.

This example uses lit-element as a base class. But it works with other web component libraries also. Make sure all routes start with "/".

import { LitElement, html } from "lit";

export class AppRoot extends LitElement {
  routes = [
    {
      path: "/",
      redirect: "/home",
    },

//   For pages without lazyloading, use like this
    {
      component: "<home-page></home-page>",
      path: "/home",
    },

  
//   For pages with lazyloading, use like this
    {
      component: "<products-page></products-page>",
      path: "/products",
      bundle: () => import("./pages/products"),
    },

// Use * to match multiple paths
     {
      component: "<products-page></products-page>",

// Mathes all products path because of * symbol
      path: "/products/*",
      bundle: () => import("./pages/products"),
    },

// If the component to be rendered has properties, add it to the props object like the example shown below. 
     {
      component: "<products-page-two></products-page-two>",
      path: "/products/pagetwo",


// Properties added to route here. The route property is a regular js object
      props : {
        propNameOne: 'some value'
        propNameTwo: '30'
      },

    },

    {

      component: "<products-page-three></products-page-three>",
      path: "/products/pagethree",
      props : {
        // passed a route property in this example
        routes: [
           {
            component: "<products-page-custom></products-page-custom>",
            path: "/products-custom",
            bundle: () => import("./pages/custom"),
          },
        ]
      },

    },

    // use * for pages with routes that don't match.
    {
      path: "/*",
      component: "<page-not-found></page-not-found>",
      bundle: () => import("./pages/page-not-found"),
    },
  ];

  render() {
    return html`<eag-router .routes=${this.routes}></eag-router>`;
  }
}

customElements.define("app-root", AppRoot);

You can import these other things from eagrouter. More documentation coming soon.

import { Route, navigationEvents$, NavState, queryString$, param$, routerHistory } from "eagrouter";


// "queryString$, navigationEvents$ and paramquot; are just regular observables.


// Use this to get the full query string when making http requests 

queryString$.subscribe(fullQuery => {

   console.log(queryString)
})

// Use this to get the current navigation state. 
// Use "NavState" to know the type of navigation available
navigationEvents$.subscribe(navState => {
   console.log(queryString)
})

// Get a specific query param like this 
param$('someId').subscribe(param => {
   console.log(param)
})

// For programmatic routing use the 
// Router history object
routerHistory.push("some-route");

For child paths, use the router child element in the component of interest.

<eag-router-child></eag-router-child>

Example one

// ..........


export class ProductsPage extends LitElement {


  // Use the full path to reference the child component.

  

  routes = [
    {
      component: "<products-page-one></products-page-one>",
    
      path: "/products/pageone",
    },
     {
      component: "<products-page-two></products-page-two>",
      path: "/products/pagetwo",
    },

  ];

  render() {
    return html`
    
    <eag-router-child .routes=${this.routes}></eag-router-child>`;
  }
}

customElements.define("products-page-two", ProductsPage);

Example two

// ..........
// In this example the routes was passed as a property from the parent. 
// Choose one method. Do not use both methods at the same time for a component.


import {state} from 'lit/decorators.js'; // for projects using litelement

export class ProductsPageTwo extends LitElement {

  // Use the full path to reference the child component.

  // This examples assumes that Lit element and typescript  was used.

  // Here the routes is passed as a property from the parent

  // If you are not using typescript or lit element, all you have to do is make sure this property is reactive.;
  @state()
  routes = [];

  render() {
    return html`
    
    <eag-router-child .routes=${this.routes}></eag-router-child>`;
  }
}

customElements.define("products-page-two", ProductsPageTwo);

Router Guards

To guard a path; add a guard property to the object in the array. The property should return a boolean value. It can also take an observable or promise that returns a boolean value

// This function just returns a regular promise
const ireturnAPromise = () => {
  const myFirstPromise = new Promise((resolve, reject) => {
    resolve(true) 
  })
return myFirstPromise
}

// ............
    {
      component: "<somepage-page></somepage-page>",
      path: "/products/xy",
      guard: () => false 
    },
    {
      component: "<somepage2-page></somepage2-page>",
      path: "/products/xyz",
      guard: () => ireturnAPromise()
    },
    {
      component: "<somepage3-page></somepage3-page>",
      path: "/products/xyz2",
      guard: () => of(true)
    }

You can find me on linkedin to ask for more info. This project is stable but is in beta state for now. Please use and drop issues if any on github. https://www.linkedin.com/in/emmanuel-agarry-a22931122/