@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
  • About @riogz/router
  • Core Concepts
  • Installation & Setup
  • Route configuration
  • Observing state
  • API Reference
• 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'
      }
    ]
  }
]

🤝 Compatibility

• Node.js: 14+
• TypeScript: 4.0+
• React: 17.0+ (for @riogz/react-router)
• Browsers: modern browsers with ES2018 support

📄 License

MIT © Vyacheslav Krasnyanskiy

🤝 Contributing

We welcome contributions from the community! Read the contributor's guide for detailed information on how to contribute to the project.

🔗 Links

• GitHub
• Issues
• Contributing Guide
• Changelog