@zenithbuild/router

File-based SPA router for Zenith framework with deterministic, compile-time route resolution.

Features

- 📁 File-based routing — Pages in pages/ directory become routes automatically
- ⚡ Compile-time resolution — Route manifest generated at build time, not runtime
- 🔗 ZenLink component — Declarative navigation with prefetching
- 🧭 Programmatic navigation — navigate(), prefetch(), isActive() APIs
- 🎯 Type-safe — Full TypeScript support with route parameter inference
- 🚀 Hydration-safe — No runtime hacks, works seamlessly with SSR/SSG

Installation

``bash
bun add @zenithbuild/router
`

Usage

$3

`ts
import { navigate, prefetch, isActive, getRoute } from '@zenithbuild/router'

// Navigate to a route
navigate('/about')

// Navigate with replace (no history entry)
navigate('/dashboard', { replace: true })

// Prefetch a route for faster navigation
prefetch('/blog')

// Check if a route is active
if (isActive('/blog')) {
console.log('Currently on blog section')
}

// Get current route state
const { path, params, query } = getRoute()
`

$3

`html
About Us


Blog


GitHub
`

$3

The router generates a route manifest at compile time:

`ts
import { generateRouteManifest, discoverPages } from '@zenithbuild/router/manifest'

const pagesDir = './src/pages'
const manifest = generateRouteManifest(pagesDir)

// manifest contains:
// - path: Route pattern (e.g., /blog/:id)
// - regex: Compiled RegExp for matching
// - paramNames: Dynamic segment names
// - score: Priority for deterministic matching
`

Route Patterns

| File Path | Route Pattern |
|-----------|---------------|
| pages/index.zen | / |
| pages/about.zen | /about |
| pages/blog/index.zen | /blog |
| pages/blog/[id].zen | /blog/:id |
| pages/posts/[...slug].zen | /posts/*slug |
| pages/[[...all]].zen | /*all? (optional) |

Architecture

`
@zenithbuild/router
├── src/
│ ├── index.ts # Main exports
│ ├── types.ts # Core types
│ ├── manifest.ts # Build-time manifest generation
│ ├── runtime.ts # Client-side SPA router
│ └── navigation/
│ ├── index.ts # Navigation exports
│ ├── zen-link.ts # Navigation API
│ └── ZenLink.zen # Declarative component
`

API Reference

$3

- navigate(path, options?) — Navigate to a path
- prefetch(path) — Prefetch a route for faster navigation
- isActive(path, exact?) — Check if path is currently active
- getRoute() — Get current route state
- back(), forward(), go(delta) — History navigation

$3

- discoverPages(pagesDir) — Find all .zen files in pages directory
- generateRouteManifest(pagesDir) — Generate complete route manifest
- filePathToRoutePath(filePath, pagesDir) — Convert file path to route
- routePathToRegex(routePath) — Compile route to RegExp

$3

- RouteState — Current route state (path, params, query)
- RouteRecord — Compiled route definition
- NavigateOptions — Options for navigation
- ZenLinkProps` — Props for ZenLink component

License

MIT

zenith-router