JongRouter

JongRouter is a lightweight client-side router for Web Components, built with Vanilla JavaScript. It enables Single Page Application (SPA) navigation without page reloads while staying framework-agnostic. Designed for developers who want a simple router for Web Components without bringing in a heavy framework.

Features

• SPA Navigation Navigate without reloading the page using the router-link attribute.
• Route Guards Protect routes with custom guard logic before navigation.
• Nested Routing Easily compose child routers inside Web Components.
• Shadow DOM Support Works seamlessly with Web Components using Shadow DOM.
• Route Parameters Dynamic routes like /profile/:username.
• Query Parameters Access query strings like /profile/jong?tab=settings.
• Route Data Pass static metadata to components.
• Programmatic Navigation Navigate using router.navigateTo().
• 404 Page Handling Built-in fallback route using **.
• Buttons & Links Support Works with both and elements.

Installation

Include the jong-router.js script in your HTML file.

Plug & Play, Import directly from cdn

<!-- via html -->
<script type="module" src="https://cdn.jsdelivr.net/npm/jong-router@latest/dist/jong-router.min.js"></script>

// via js
// latest 
import JongRouter from 'https://cdn.jsdelivr.net/npm/jong-router@latest/dist/jong-router.min.js'

// or specific version
import JongRouter from 'https://cdn.jsdelivr.net/npm/[email protected]/dist/jong-router.min.js'

Or Install using NPM

// or via npm
npm i jong-router   

Usage

1. Initialize the Router:

const routes = [

  { pattern: '/', component: import('./components/HomeComponent') },

  { pattern: '/about', component: import('./components/AboutComponent') },

  { pattern: '**', html: `<h2>Page not found</h2>` }

]

const router = new JongRouter(
  routes,
  document.getElementById('app')
)

router.init()

2. Create Components:

Create your web components for each route.

class HomeComponent extends HTMLElement {

  connectedCallback() {

    this.innerHTML = `<h1>Home Page</h1>`

  }

}

customElements.define('home-component', HomeComponent)

3. Navigate with Router Links:

Use the router-link attribute to create navigation links.

<!-- Example: index.html -->

<a router-link href="/">Home</a>

<a router-link href="/about">About</a>

Buttons also work with router-link

<button router-link href="/about">
Go to About
</button>

4. Programmatic Navigation Components can navigate programmatically.

Example outside component

import { router } from "../router-instance"

router.navigateTo("/profile/admin")

Example inside a component

this.shadowRoot
  .getElementById("btn")
  .addEventListener("click", () => {

    this.navigateTo("/profile/admin")

  })

5. Guards

Implement guards for route conditions

const router = new JongRouter([

  {

    pattern: '/dashboard',

    component: import('./components/DashboardComponent'),

    guards: [() => isAuthenticated()],

    redirect: '/login',  

  },

  { pattern: '/login', component: import('./components/LoginComponent') }, 
  // ...other routes

]);



function isAuthenticated(ctx) {

  // Your authentication logic here
  console.log(ctx.path)
  console.log(ctx.params)

  return true;

}

6. Handle Route Parameters and Query Parameters:

Define dynamic routes Parameter:

{
  pattern: "/profile/:username",
  component: import("./ProfileComponent")
}

Access inside the component

const params = JSON.parse(
  this.getAttribute("route-params")
)

console.log(params.username)

Define query parameter

/profile/jong?tab=settings

Inside component

const query = JSON.parse(
  this.getAttribute("query-params")
)

console.log(query.tab)

7. Route Data Attach metadata to routes

{
  pattern: "/profile/:username",
  component: import("./ProfileComponent"),
  data: { role: "admin" }
}

Access in component

const data = JSON.parse(
  this.getAttribute("route-data")
)

8. Nested Routes & Sub-Outlest

JongRouter supports hierarchical routing. This allows you to render a "Shell" or "Layout" component and then inject sub-pages into it dynamically.

Step 1: Define Child Routes Create a separate file for your sub-navigation.

Example

// samples/nested/nested-routes.ts
import { IRoute } from "../../src/jong-router"

const routes: IRoute[] = [
  { pattern: "/nested/c1", html: "<p>Child Page 1</p>" },
  { pattern: "/nested/c2", html: "<p>Child Page 2</p>" },
  { pattern: "/nested/c3", html: "<p>Child Page 3</p>" }
]

export default routes

Step 2: Prepare the Parent Component Your parent component must contain an element with the router-outlet attribute. This is where the child routes will be rendered.

A parent component can create its own router instance w children routes

// samples/nested/sample-nested.ts
export default class SampleNested extends HTMLElement {
  connectedCallback() {
    this.innerHTML = `
      <div class="layout">
        <nav>
          <a href="/nested/c1" router-link>Go to C1</a>
          <a href="/nested/c2" router-link>Go to C2</a>
        </nav>
        <!-- Child routes will appear here -->
        <div router-outlet></div> 
      </div>
    `;
  }
}

Step 3: Register Nested Routes Pass the children to the parent route. You can use a static array or a function for Lazy Loading.

const routes: IRoute[] = [
  {
    pattern: '/nested',
    component: import('./samples/nested/sample-nested'),
    // Lazy-load the child route definitions
    children: () => import("./samples/nested/nested-routes") 
  }
]

Playground & Examples

Playground & Examples The repository contains a Playground demonstrating:

• Basic routing
• Guarded routes
• Nested routes
• Query parameters
• Route parameters
• Programmatic navigation
• Buttons & router-link navigation

Why JongRouter?

JongRouter focuses on simplicity and Web Component compatibility. Unlike many routers, it:

• Works without frameworks
• Supports Shadow DOM
• Keeps the API extremely small
• Is easy to embed in micro-frontend architectures

Perfect for:

• Web Component apps
• Micro-frontends
• Lightweight SPAs
• Vanilla JS projects

How to run development server?

git clone [email protected]:josnin/jong-router.git 
cd ~/Documents/jong-router/
npm install
npm run dev

Help

Need help? Open an issue in: ISSUES

Contributing

Want to improve and add feature? Fork the repo, add your changes and send a pull request.