Olas

Appearance

API reference > @kontsedal/olas-router

olas-router package ​

Functions ​

Function

Description

createRouterAdapter(initial)

Build a router adapter — a paired { plugin, Bridge }.

Wire-up:

tsx
import { createRouterAdapter, RouteParamsScope } from '@kontsedal/olas-router'

const adapter = createRouterAdapter()
const root = createRoot(appController, { deps, plugins: [adapter.plugin] })

function App() {
  // TanStack Router:
  const params = useParams({ strict: false })
  const search = useSearch({ strict: false })
  const location = useLocation()

  // React Router v6:
  // const params = useParams()
  // const [sp] = useSearchParams()
  // const { pathname } = useLocation()

  return (
    <OlasProvider root={root}>
      <adapter.Bridge params={params} search={search} pathname={location.pathname}>
        <YourRoutes />
      </adapter.Bridge>
    </OlasProvider>
  )
}

In any controller:

ts
const params = ctx.inject(RouteParamsScope)
const userId = computed(() => params.value.userId)

The adapter is router-agnostic by design — wire whatever client-side router you use. Next.js's app router is not supported: its server components run outside the browser tree a controller lives in.

**SSR:** pass initial so the scopes hold real route state during the server render — the Bridge pushes state in a client-only effect, so without seeding, params / search / pathname are empty ({} / '') for the whole server render. Derive initial from the request URL:

ts
const adapter = createRouterAdapter({
  params: matchedRouteParams,        // from your server router match
  search: parsedSearch,
  pathname: url.pathname,
})

Variables ​

Variable

Description

RouteParamsScope

Route URL params. Shape matches what a typical router exposes:{ userId: '42', tab: 'profile' } etc. Values are string | undefined —undefined for an optional segment not present in the current URL (matches React Router). If your router parses them to other types, do that in the consumer controller (computed(() => Number(params.value.id))), and guard the undefined (e.g. enabled: () => params.value.id !== undefined).

RoutePathnameScope

Current pathname (URL path portion, no search/hash). E.g. '/users/42'. Useful for analytics, breadcrumbs, or coarse-grained route-change effects.

ROUTER_PLUGIN_NAME

The plugin's name.

RouteSearchScope

Parsed search-string params. Values are unknown because routers vary: TanStack Router parses numbers / booleans, React Router gives strings. Narrow in the consumer.

Type Aliases ​

Type Alias

Description

RouterAdapter

Result of createRouterAdapter(). plugin goes increateRoot({ plugins: [adapter.plugin] }) and provides the three route scopes; Bridge mounts inside the React tree and pushes router state into them on every change.

RouteState

A snapshot of route state. Params values are string | undefined to match React Router (an optional segment not present in the current URL isundefined), not just string. Pass to createRouterAdapter(initial) on the server to seed the scopes before the render — the Bridge only pushes state in a (client-only) effect, so without seeding, route-scoped signals would be empty for the entire server render.

Released under the MIT License.