# @iyulab/router Client-side SPA router for Lit and React with URLPattern matching, nested routes, and route lifecycle events. ## Installation ```bash npm install @iyulab/router ``` ## Quick Start ```typescript import { Router } from '@iyulab/router'; import { html } from 'lit'; const router = new Router({ root: document.body, basepath: '/', routes: [ { index: true, render: () => html`` }, { path: '/users/:id', render: (ctx) => html`` }, ], fallback: { render: (ctx) => html``, }, }); router.go('/users/1'); ``` ## Skills Usage Install the `iyulab-router` skill for agent-friendly package guidance. ```bash npx skills add iyulab/node-router ``` ```bash npx skills add ./node_modules/@iyulab/router ``` ## Route Guards Use `enter` to run guard logic before rendering. ```typescript const router = new Router({ root: document.body, enter: (ctx) => { if (!isAuthenticated() && ctx.pathname !== '/login') return '/login'; return true; }, routes: [ { path: '/login', render: () => html`` }, { path: '/admin', enter: () => hasRole('admin') || '/forbidden', render: () => html``, }, ], }); ``` `enter` return values: - `true` (or `undefined`): continue - `false`: cancel navigation - `string`: redirect to that path ## Route Metadata Attach metadata to routes using `metadata`. The router merges metadata from parent to child and exposes it on `ctx.metadata`. ```typescript const routes = [ { path: '/dashboard', metadata: { requiresAuth: true, section: 'dashboard' }, render: () => html`

`, children: [ { path: 'settings', metadata: { tab: 'settings' }, render: (ctx) => html``, }, ], }, ]; ``` ## Nested Routes Parent routes must render `` to host child route content. ```typescript const routes = [ { path: '/nested', render: () => html`

`, children: [ { index: true, render: () => html`` }, { path: 'lit', render: () => html`` }, { path: 'react', render: () => }, ], }, ]; ``` ## Link and Outlet Components - ``: SPA-aware anchor element - ``: render target for matched route output `` supports `href`, `target`, and `rel`. ```html Docs External ``` React wrappers: ```tsx import { ULink, UOutlet } from '@iyulab/router/react'; ``` ## Route Events The router dispatches events on `window`: - `route-begin` - `route-progress` - `route-done` - `route-error` ```typescript window.addEventListener('route-progress', (e) => { console.log(e.progress); }); ``` ## License MIT License. See [LICENSE](LICENSE).

iyulab-router

Installation

SKILL.md