Routing

Routes are owned by features, not by apps. The application shell composes each feature's routes export into a single router instance.

1. The Router Instance

@vh5/app-shell creates the router once. Adapter apps do not configure routes.

// packages/app-shell/src/router/index.ts
import { createRouter, createWebHistory } from 'vue-router';
import { mergeRouteModules } from '@vh5/utils';
import { authRoutes } from '@vh5/feature-auth';
import { homeRoutes } from '@vh5/feature-home';
import { productRoutes } from '@vh5/feature-product';
import { userRoutes } from '@vh5/feature-user';
import { BasicLayout } from '../layouts/BasicLayout.vue';

const featureRoutes = mergeRouteModules([
  ...homeRoutes,
  ...productRoutes,
  ...userRoutes,
]);

export const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes: [
    { path: '/', component: BasicLayout, children: featureRoutes },
    ...authRoutes, // /login, /forgot
    {
      path: '/:pathMatch(.*)*',
      component: () => import('../views/NotFound.vue'),
    },
  ],
});

2. Defining a Feature's Routes

// packages/features/product/src/routes.ts
import type { RouteRecordRaw } from 'vue-router';

export const productRoutes: RouteRecordRaw[] = [
  {
    path: 'product',
    name: 'product-list',
    component: () => import('./views/List.vue'),
    meta: {
      title: 'Products',
      authority: ['user', 'admin'], // role-based access
      tab: true, // show in BasicLayout tabbar
    },
  },
  {
    path: 'product/:id',
    name: 'product-detail',
    component: () => import('./views/Detail.vue'),
    meta: { title: 'Product Detail', authority: ['user', 'admin'] },
  },
];

meta keys recognised by the shell:

Key	Type	Purpose
title	string	Document title + navbar title
authority	string[]	Roles allowed to access (omit ⇒ public for authenticated)
public	boolean	Accessible without login
tab	boolean	Render entry in the bottom tab bar
keepAlive	boolean	Wrap the view in <KeepAlive>

3. Permission Pipeline

A single global beforeEach guard is registered in @vh5/app-shell/router/guards.ts:

router.beforeEach(async (to) => {
  startProgress();

  if (to.meta.public) return true;

  const auth = useAuthStore();
  if (!auth.isAuthenticated) {
    return { name: 'login', query: { redirect: to.fullPath } };
  }

  if (
    Array.isArray(to.meta.authority) &&
    !to.meta.authority.some(auth.hasRole)
  ) {
    return { name: 'forbidden' };
  }

  return true;
});

router.afterEach(() => stopProgress());

Frontend filtering is delegated to generateRoutesByFrontend() from @vh5/utils for screens that show a dynamic menu (e.g. an admin section).

4. Type-safe Names

unplugin-vue-router generates types/typed-router.d.ts. Inside features prefer named navigation:

router.push({ name: 'product-detail', params: { id } });

5. Backend-Driven Routes (Optional)

For apps that load their menu from the server:

import { generateRoutesByBackend } from '@vh5/utils';
import { fetchMenuListAsync } from '@vh5/services';

const routes = await generateRoutesByBackend({
  fetchMenuListAsync,
  layoutMap: { BasicLayout },
  pageMap: import.meta.glob('@/features/**/views/*.vue'),
});

router.addRoute({ path: '/', component: BasicLayout, children: routes });

The same meta.authority filtering applies to backend routes.

6. Layout & Title

BasicLayout provides:

• top navbar with meta.title
• bottom tab bar built from routes whose meta.tab === true
• a slot for the active view

Document title is updated by the shell:

watchEffect(() => {
  const title = router.currentRoute.value.meta?.title as string | undefined;
  useTitle(title ? `${title} - Vue H5 Template` : 'Vue H5 Template');
});