@molecule/app-routing-vue-router

Vue Router provider for @molecule/app-routing.

This package provides a Vue Router implementation of the molecule Router interface, allowing you to use molecule's routing abstractions with Vue Router.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

<!-- App.vue (or a root-level component INSIDE the vue-router app) -->
<script setup lang="ts">
import { useLocation, useMoleculeRouterProvider } from '@molecule/app-routing-vue-router'

// Builds the adapter from vue-router's useRouter()/useRoute() AND bonds it, so
// molecule packages using @molecule/app-routing share THIS router. No manual
// setRouter watch needed.
const router = useMoleculeRouterProvider()

const location = useLocation()
function goToProfile() {
  router.value.navigate('/profile')
}
</script>

<template>
  <p>Current path: {{ location.pathname }}</p>
  <button @click="goToProfile">Go to Profile</button>
</template>

Type

provider

Installation

npm install @molecule/app-routing-vue-router @molecule/app-i18n @molecule/app-routing vue vue-router

API

Interfaces

VueRouterConfig

Vue Router-specific configuration.

interface VueRouterConfig {
  /**
   * Vue Router instance (from useRouter).
   */
  router?: VueRouterInstance

  /**
   * Current route (from useRoute).
   */
  route?: RouteLocationNormalizedLoaded

  /**
   * Initial route definitions for named routes.
   */
  routes?: RouteDefinition[]
}

VueRouterComposable

Vue Router composable return type.

interface VueRouterComposable {
  /**
   * Vue Router instance.
   */
  router: VueRouterInstance

  /**
   * Current route.
   */
  route: RouteLocationNormalizedLoaded
}

RouteLocation

Current URL decomposed into pathname, search string, hash, navigation state, and unique key.

interface RouteLocation {
  /**
   * Current pathname.
   */
  pathname: string
  /**
   * Query string (including leading ?).
   */
  search: string
  /**
   * Hash (including leading #).
   */
  hash: string
  /**
   * State data passed with navigation.
   */
  state?: unknown
  /**
   * Unique key for this location.
   */
  key?: string
}

RouteMatch

Result of matching a URL against a route pattern (path, params, query string).

interface RouteMatch<Params extends RouteParams = RouteParams> {
  /**
   * Route path pattern.
   */
  path: string
  /**
   * Matched URL pathname.
   */
  pathname: string
  /**
   * Route parameters.
   */
  params: Params
  /**
   * Whether this is an exact match.
   */
  isExact: boolean
}

NavigateOptions

Options for programmatic navigation (replace vs push, carry state, preserve query/hash).

interface NavigateOptions {
  /**
   * Replace current history entry instead of pushing.
   */
  replace?: boolean
  /**
   * State to pass with navigation.
   */
  state?: unknown
  /**
   * Preserve current query params.
   */
  preserveQuery?: boolean
  /**
   * Preserve current hash.
   */
  preserveHash?: boolean
}

RouteDefinition

Route configuration entry (path pattern, name, auth requirements, roles, children).

interface RouteDefinition {
  /**
   * Route path pattern.
   */
  path: string
  /**
   * Route name (for named routes).
   */
  name?: string
  /**
   * Whether the route requires exact matching.
   */
  exact?: boolean
  /**
   * Whether the route requires authentication.
   */
  requiresAuth?: boolean
  /**
   * Required roles/permissions.
   */
  roles?: string[]
  /**
   * Route metadata.
   */
  meta?: Record<string, unknown>
  /**
   * Child routes.
   */
  children?: RouteDefinition[]
}

Router

Client-side router providing navigation, guards, route matching, and history control.

All routing providers must implement this interface.

interface Router {
  /**
   * Returns the current route location (pathname, search, hash, state).
   */
  getLocation(): RouteLocation
  /**
   * Gets the current route params.
   */
  getParams<T extends RouteParams = RouteParams>(): T
  /**
   * Gets the current query params.
   */
  getQuery(): QueryParams
  /**
   * Gets a specific query parameter.
   */
  getQueryParam(key: string): string | undefined
  /**
   * Gets the current hash.
   */
  getHash(): string
  /**
   * Navigates to a path.
   */
  navigate(path: string, options?: NavigateOptions): void
  /**
   * Navigates to a named route.
   */
  navigateTo(
    name: string,
    params?: RouteParams,
    query?: QueryParams,
    options?: NavigateOptions,
  ): void
  /**
   * Goes back in history.
   */
  back(): void
  /**
   * Goes forward in history.
   */
  forward(): void
  /**
   * Goes to a specific point in history.
   */
  go(delta: number): void
  /**
   * Updates the current query params.
   */
  setQuery(params: QueryParams, options?: NavigateOptions): void
  /**
   * Updates a specific query parameter.
   */
  setQueryParam(key: string, value: string | undefined, options?: NavigateOptions): void
  /**
   * Updates the current hash.
   */
  setHash(hash: string, options?: NavigateOptions): void
  /**
   * Checks if a path matches the current location.
   *
   * @returns `true` if the path matches the current route.
   */
  isActive(path: string, exact?: boolean): boolean
  /**
   * Matches a path pattern against a pathname.
   */
  matchPath<Params extends RouteParams = RouteParams>(
    pattern: string,
    pathname: string,
  ): RouteMatch<Params> | null
  /**
   * Generates a URL from a named route.
   */
  generatePath(name: string, params?: RouteParams, query?: QueryParams): string
  /**
   * Subscribes to route changes.
   */
  subscribe(listener: RouteChangeListener): () => void
  /**
   * Adds a navigation guard.
   */
  addGuard(guard: NavigationGuard): () => void
  /**
   * Registers route definitions.
   */
  registerRoutes(routes: RouteDefinition[]): void
  /**
   * Gets all registered routes.
   */
  getRoutes(): RouteDefinition[]
  /**
   * Destroys the router.
   */
  destroy(): void
}

RouterConfig

Configuration options for creating a router instance.

interface RouterConfig {
  /**
   * Router mode.
   */
  mode?: 'history' | 'hash' | 'memory'
  /**
   * Base path.
   */
  basePath?: string
  /**
   * Initial routes.
   */
  routes?: RouteDefinition[]
}

Types

RouteParams

URL path parameter key-value map extracted from dynamic route segments (e.g. { id: '123' }).

type RouteParams = Record<string, string>

QueryParams

URL query string parameter map (single values or arrays for repeated keys).

type QueryParams = Record<string, string | string[] | undefined>

GuardResult

Navigation guard result.

type GuardResult =
  | boolean
  | string
  | {
      path: string
      replace?: boolean
    }
  | void

NavigationGuard

Navigation guard function invoked before each navigation. Return false to cancel, a string/path to redirect, or void to allow.

type NavigationGuard = (
  to: RouteLocation,
  from: RouteLocation | null,
) => GuardResult | Promise<GuardResult>

• to — The target route location being navigated to.
• from — The current route location being navigated away from, or null on initial load.

RouteChangeListener

Callback invoked on each route change with the new location and the navigation action that triggered it.

type RouteChangeListener = (location: RouteLocation, action: 'push' | 'replace' | 'pop') => void

Functions

useMoleculeRouter(routes)

Composable to create and provide a molecule Router.

function useMoleculeRouter(routes?: RouteDefinition[]): ComputedRef<Router>

• routes — Optional route definitions for named routes

Returns: The molecule Router instance

useMoleculeRouterProvider(routes)

Composable that builds the molecule Router from Vue Router AND bonds it as the active singleton via @molecule/app-routing's setRouter.

Call this ONCE near the app root (e.g. in App.vue's setup). It watches the adapter with { immediate: true }, so setRouter runs synchronously in setup and re-runs whenever the route changes — meaning @molecule/app-routing's navigate()/getRouter() drive the REAL Vue Router (not the core's auto-created fallback browser router) for the rest of the app. Returns the same reactive router ref so you can also use it locally.

function useMoleculeRouterProvider(routes?: RouteDefinition[]): ComputedRef<Router>

• routes — Optional route definitions for molecule named routes.

Returns: The reactive molecule Router ref (already bonded).

useLocation()

Composable to get the current location as a reactive ref.

function useLocation(): ComputedRef<RouteLocation>

Returns: Reactive location ref

useParams()

Composable to get route params as a reactive ref.

function useParams(): ComputedRef<T>

Returns: Reactive params ref

useQuery()

Composable to get query params as a reactive ref.

function useQuery(): ComputedRef<QueryParams>

Returns: Reactive query params ref

useNavigate()

Composable to get a navigate function.

function useNavigate(): (path: string, options?: { replace?: boolean; state?: unknown }) => void

Returns: Navigate function

useIsActive(path, exact)

Composable to check if a path is active.

function useIsActive(path: string, exact?: boolean): ComputedRef<boolean>

• path — Path to check
• exact — Whether to require exact match

Returns: Reactive boolean ref

useRouteChange(callback)

Composable to subscribe to route changes.

function useRouteChange(
  callback: (location: RouteLocation, action: 'push' | 'replace' | 'pop') => void,
): void

• callback — Callback to run on route change

useNavigationGuard(guard)

Composable to add a navigation guard.

function useNavigationGuard(
  guard: (
    to: RouteLocation,
    from: RouteLocation | null,
  ) =>
    | boolean
    | string
    | { path: string; replace?: boolean }
    | void
    | Promise<boolean | string | { path: string; replace?: boolean } | void>,
): void

• guard — Guard function

createVueRouter(config)

Creates a Vue Router adapter that implements the molecule Router interface.

function createVueRouter(config?: VueRouterConfig): Router

• config — Configuration with Vue Router's router instance, current route, and optional routes.

Returns: A molecule Router with navigation, guards, query/hash management, and route matching.

parseVueQuery(query)

Converts a Vue Router query object (with nullable values) into a molecule QueryParams object. Filters out null values and preserves arrays.

function parseVueQuery(
  query: Record<string, LocationQueryValue | LocationQueryValue[]>,
): QueryParams

• query — The Vue Router LocationQuery object from route.query.

Returns: A molecule QueryParams map with only non-null values.

toVueQuery(params)

Converts a molecule QueryParams object to a Vue Router LocationQueryRaw object. Omits keys with undefined values.

function toVueQuery(params: QueryParams): LocationQueryRaw

• params — The molecule query parameters.

Returns: A LocationQueryRaw compatible with Vue Router's router.push({ query }).

stringifyQuery(params)

Converts a molecule QueryParams object to a URL search string (e.g. ?key=val&arr=1&arr=2). Omits keys with undefined values.

function stringifyQuery(params: QueryParams): string

• params — The query parameters to stringify.

Returns: A URL search string starting with ?, or empty string if no params.

matchPath(pattern, pathname, exact)

Matches a path pattern (with :param segments and * wildcards) against a pathname.

function matchPath(pattern: string, pathname: string, exact?: boolean): RouteMatch<Params> | null

• pattern — The route pattern (e.g. '/users/:id').
• pathname — The actual URL pathname to test.
• exact — Whether to require an exact match (default true). Set to false for prefix matching.

Returns: A RouteMatch with extracted params, or null if no match.

generatePath(pattern, params)

Generates a concrete path from a route pattern by replacing :param segments with values. Throws if a required param is missing.

function generatePath(pattern: string, params?: RouteParams): string

• pattern — The route pattern (e.g. '/users/:id').
• params — A map of param names to values.

Returns: The resolved path string with params URL-encoded.

normalizeParams(params)

Normalizes Vue Router params (which may contain string | string[]) into molecule RouteParams (plain string values). Array values are joined with '/'.

function normalizeParams(params: Record<string, string | string[]>): RouteParams

• params — The Vue Router params object from route.params.

Returns: A flat RouteParams map with string values only.

Constants

MOLECULE_ROUTER_KEY

Symbol for providing molecule router in Vue.

const MOLECULE_ROUTER_KEY: typeof MOLECULE_ROUTER_KEY

provider

Default Vue Router provider (basic, no hooks). For full functionality, use createVueRouter with useRouter/useRoute.

const provider: Router

Core Interface

Implements @molecule/app-routing interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setRouter } from '@molecule/app-routing'
import { provider } from '@molecule/app-routing-vue-router'

export function setupRoutingVueRouter(): void {
  setRouter(provider)
}

Injection Notes

Requirements

Peer dependencies:

• @molecule/app-i18n ^1.0.1
• @molecule/app-routing ^1.0.1
• vue ^3.4.0
• vue-router ^4.3.0

Runtime Dependencies

• @molecule/app-i18n

• @molecule/app-routing

• vue

• vue-router

• Use useMoleculeRouterProvider() once near the app root to bond the router. It builds the adapter from useRouter()/useRoute() and calls @molecule/app-routing's setRouter in an { immediate: true } watch, so other molecule packages' navigate()/getRouter() drive the real Vue Router (SPA navigation). useMoleculeRouter() (non-bonding) still exists for local use; if you only ever call that, molecule packages silently get the core's auto-created fallback browser router and navigate with full-page reloads.

• Do NOT wire the exported provider const in a vue-router app — it is a no-hooks fallback (empty params, window.location.href navigation).

• Composables must run inside a component tree that has the vue-router plugin installed (app.use(router)), since they call useRouter()/useRoute().