Skip to content
Development guideVersion 6.0.2

Routes, menus, and permissions ​

After sign-in, GET /admin/route-config returns the routes available to the session, ordered by meta.order. Menus and breadcrumbs use the route tree, and Vue Router registers the expanded page records. The initial mock routes live in packages/demo-data/src/routes.json. The shell reserves sign-in, profile, and status pages. The default router uses hashes, for example /ray-template/#/orders.

Validate route configuration ​

Change the path, name, or view ID to see the shared validator's result. This example registers the overview view.

Valid routes: 1
View example source
vue
<template>
  <div class="ray-demo ray-demo-fields">
    <div>
      <label :for="id">{{
        english ? 'Route configuration' : '路由配置'
      }}</label>
      <textarea
        :id="id"
        v-model="source"
        rows="8"
        spellcheck="false"
        :aria-invalid="result.invalid"
      />
      <output class="ray-demo-result">{{ result.message }}</output>
    </div>
  </div>
</template>

<script setup lang="ts">
import { createRouteContract } from '@ray-template/routing'
import { useData } from 'vitepress'
import { computed, ref, useId } from 'vue'

const { lang } = useData()
const english = computed(() => lang.value.startsWith('en'))
const load = async () => ({})
const { parseRouteConfig } = createRouteContract({
  layout: load,
  managementPath: '/route-management',
  findRouteView: (view) =>
    view === 'overview' ? { name: 'Overview', load } : void 0,
  findRouteViewId: (candidate) => (candidate === load ? 'overview' : void 0),
})
const id = useId()
const source = ref(
  JSON.stringify(
    {
      version: 1,
      routes: [
        {
          path: '/overview',
          component: 'overview',
          name: 'Overview',
          meta: {},
        },
      ],
    },
    null,
    2,
  ),
)
const result = computed(() => {
  try {
    const { routes } = parseRouteConfig(source.value)

    return {
      invalid: false,
      message: `${english.value ? 'Valid routes' : '有效路由'}: ${routes.length}`,
    }
  } catch (error) {
    return {
      invalid: true,
      message: error instanceof Error ? error.message : String(error),
    }
  }
})
</script>

<style scoped>
textarea {
  width: 100%;
  padding: 10px;
  border: 1px solid var(--vp-c-divider);
  border-radius: 6px;
  background: var(--vp-c-bg);
  font-family: var(--vp-font-family-mono);
  resize: vertical;
}
</style>

Edit routes and connect the API ​

With routes:write, the visual and JSON editors load the complete draft from the editor endpoint and save it with PUT /admin/route-config. The runtime routes then reload. Mock writes persist in the current browser, and you can switch to a local or built-in configuration. In standard backend mode, the remote configuration is authoritative and load failures surface as errors. If you configured the read-only VITE_ROUTE_CONFIG_URL, select the remote source in the JSON editor and enable the remote configuration to resume reading that URL. Save edits to a read-only source locally or export the draft.

The request body is { version: 1, routes: [...] }. Both read and write results are in data in the shared { code, msg, data } envelope. component must be a registered ID in router/config/views.ts. Register the ID for a new frontend page before returning its route from the API. Standard backend contract

Common metadata ​

FieldBehavior
i18nKey / noLocalTitleUse a translation key or a literal menu title.
iconUse the full group-qualified icon name. Code-defined routes can also supply a VNode.
roleApplies to menus and guards. Role values must use the same type as the session.
hidden, envControl menu visibility. Route and API access have their own permission checks.
sameLevelA detail page can keep the current menu item and tab, adding its level only to the breadcrumb.
keepAliveMakes the page eligible for caching in the content area.
windowOpenOpens the configured address when the menu entry is clicked.
ignoreAutoResetScrollAllows the page to retain the content area's scroll position. See the scroll utility for details.
extraText, icon, type, and visibility of menu badges. See useBadge.

Relative child paths inherit the parent path. Built-in examples group routes by purpose and use absolute paths to preserve existing URLs. Layout and nested route examples

Sign-in and roles ​

The default sign-in route is /. When a user opens a business page without a session, the guard puts the full destination in the sign-in page's redirect parameter. After sign-in, it restores only a registered business URL the current role can still access, including its query and hash. Without a valid destination, it opens /welcome. For redirect routes, the menu and guard check permissions on the entry, each hop, and the destination. A hidden menu item may still allow direct navigation. In production, validate the session, permissions, and resource ownership on the backend.

Empty workspace and status pages ​

/welcome represents a workspace with no active business route and displays accessible entry points. It is a shell status page, like /403, /404, and /500. These pages stay outside business menus, tabs, history, and page caching. The shell reserves these four paths, their descendants and aliases, and their route names. Local and remote JSON must leave them available to the shell. A custom source may omit /dashboard or give it role restrictions.

All business tabs can be closed, including the former home page and the last open tab. Closing the active tab selects an adjacent tab. Closing the last tab or all tabs opens the empty workspace and releases the corresponding KeepAlive instances. Each concrete pathname has one tab. Query or fragment changes update the full address stored with that tab. A role change removes revoked tabs and cached instances without opening another business page automatically.

  • /403 appears for a signed-in user without access to the requested page. Closing the current page from the tab bar returns to the previous accessible page or an open accessible tab, with the workspace as the fallback.
  • /404 indicates a missing destination. query.from retains the original target.
  • /500 indicates route resolution or lazy loading failed. Retry is available when query.from still exists and is accessible.

Every status page offers a way back to the workspace. Back and Retry validate the destination as an internal, permitted route before using history or query values. useAppRoot and the old appRootRoute preference still support compatibility reads and writes. The current startup and navigation flow use the workspace behavior above.

Troubleshoot KeepAlive ​

  1. Set meta.keepAlive: true and give the route a unique name.
  2. Match the TSX defineComponent({ name }) or SFC component name to the route name. Check that the lazy-loaded module exports the intended component.
  3. Enter from the menu, change some page state, switch to another tab, and return. Also check closing the tab, direct navigation, and reloading. A browser refresh creates new component instances.
  4. If you replace the default layout content slot, provide the routing and caching behavior your application needs.

Route contract · Guard implementation