@riogz/router NPM

@riogz/router

Modern, flexible and framework-agnostic router — a continuation of router5 with improved architecture and TypeScript support.

✨ Key Features

🎯 Framework Agnostic — works with any frameworks and libraries
🔄 View/State Separation — router processes instructions and outputs state updates
🌍 Universal — works on client and server
🧩 Modular Architecture — use only what you need
⚡ High Performance — optimized algorithms and caching
🔒 Type-Safe — full TypeScript support
🛡️ Route Guards — access control and transition validation
🔗 Hierarchical Routes — nested routes and dynamic segments
🤹‍♀️ Compatable with Router5 — use your existing router5 routes, plugins and middlewares

🚀 Quick Start

Installation

# Core router
npm install @riogz/router

# For React applications
npm install @riogz/router @riogz/react-router

# For browser integration
npm install @riogz/router-plugin-browser

# For debugging
npm install @riogz/router-plugin-logger

Basic Setup

import createRouter from '@riogz/router'
import browserPlugin from '@riogz/router-plugin-browser'

const routes = [
  { name: 'home', path: '/' },
  { name: 'users', path: '/users' },
  { name: 'users.detail', path: '/:id' }
]

const router = createRouter(routes)
router.start()

// Navigation
router.navigate('users.detail', { id: '123' })

With React

import React from 'react'
import { createRouter, RouterProvider, useRouter } from '@riogz/router'
import browserPlugin from '@riogz/router-plugin-browser'

const routes = [
  { name: 'home', path: '/' },
  { name: 'users', path: '/users' },
  { name: 'users.detail', path: '/:id' }
]

const router = createRouter(routes)
router.usePlugin(browserPlugin())
router.start()

function App() {
  return (
    <RouterProvider router={router}>
      <Navigation />
         <RouteNode nodeName="home">
            <Home />
         </RouteNode>
         <RouteNode nodeName="users" children={Users} />
    </RouterProvider>
  )
}

function Navigation() {
  const router = useRouter()
  
  return (
    <nav>
      <button onClick={() => router.navigate('home')}>
        Home
      </button>
      { /* -or- */}
      <Link routeName="users">Users</Link>
    </nav>
  )

}

📚 Documentation

Introduction
Integration
- React TBD
- Browser TBD
- Node.js TBD
Advanced
- Route Guards TBD
- Plugins TBD
- Middleware TBD
- Transition Path TBD
- Route Helpers TBD
- Listeners plugin TBD
Examples
- Base examples are placed in the examples folder
- Advanced examples are placed in the Github: riogod/frontend-modules-mvvm

📦 Package Ecosystem

Core Packages

Package	Description	Version	Bundle
@riogz/router	Core router
@riogz/react-router	React integration with hooks and components

Plugins

Package	Description	Version	Bundle
@riogz/router-plugin-browser	Browser integration (History API, hash)
@riogz/router-plugin-logger	Transition logging for debugging
@riogz/router-plugin-persistent-params	Parameter persistence between transitions

Utilities

Package	Description	Version	Bundle
@riogz/router-helpers	Route manipulation utilities
@riogz/router-transition-path	Transition path computation

🎯 Core Concepts

Hierarchical Routes

const routes = [
  { name: 'app', path: '/app' },
  { name: 'app.users', path: '/users' },
  { name: 'app.users.detail', path: '/:id' },
  { name: 'app.users.detail.edit', path: '/edit' }
]

// Resulting paths:
// app → /app
// app.users → /app/users  
// app.users.detail → /app/users/:id
// app.users.detail.edit → /app/users/:id/edit

Route Guards

const router = createRouter(routes, {
  defaultRoute: 'home'
})

// Guard for authorization check
router.canActivate('admin', (toState, fromState) => {
  return user.isAuthenticated && user.hasRole('admin')
})

// Async guard
router.canActivate('users.detail', async (toState) => {
  const user = await api.getUser(toState.params.id)
  return user.exists
})

Middleware

// Transition logging
router.useMiddleware((toState, fromState) => {
  console.log(`Transition: ${fromState?.name} → ${toState.name}`)
})

// Analytics
router.useMiddleware((toState) => {
  analytics.track('page_view', {
    route: toState.name,
    params: toState.params
  })
})

Route Node Lifecycle

const routes = [
  { name: 'app', path: '/app' },
  { 
    name: 'app.users', 
    browserTitle: 'Users',
    path: '/users',
    onEnterNode: (toState, fromState, deps) => {
      console.log('Entering users node')
    },
    onExitNode: (toState, fromState, deps) => {
      console.log('Leaving users node')
    },
    onNodeInActiveChain: (toState, fromState, deps) => {
      console.log('Users node is in the active chain')
    },
    children: [
      {
        name: 'app.users.detail',
        path: '/:id'
      }
    ]
  }
]