vitepress-template

Appearance

Navigation and Routing ​

**Referenced Files in This Document** - [[ui-web/next.config.ts]](file/ui-web/next.config.ts) - [[ui-web-admin/next.config.ts]](file/ui-web-admin/next.config.ts) - [[ui-web-top/next.config.ts]](file/ui-web-top/next.config.ts) - [[ui-web/src/app/layout.tsx]](file/ui-web/src/app/layout.tsx) - [[ui-web-admin/src/app/layout.tsx]](file/ui-web-admin/src/app/layout.tsx) - [[ui-web-admin/src/app/(dashboard)/layout.tsx]](file/ui-web-admin/src/app/dashboard)/layout.tsx) - [[ui-web-admin/src/app/login/page.tsx]](file/ui-web-admin/src/app/login/page.tsx) - [[ui-web-admin/src/app/(dashboard)/tenants/page.tsx]](file/ui-web-admin/src/app/dashboard)/tenants/page.tsx) - [[ui-web-admin/src/app/(dashboard)/tenants/packages/page.tsx]](file/ui-web-admin/src/app/dashboard)/tenants/packages/page.tsx) - [[ui-web-admin/src/app/(dashboard)/tenants/menus/page.tsx]](file/ui-web-admin/src/app/dashboard)/tenants/menus/page.tsx) - [[ui-web-admin/src/app/(dashboard)/system/users/page.tsx]](file/ui-web-admin/src/app/dashboard)/system/users/page.tsx) - [[ui-web-admin/src/app/(dashboard)/system/roles/page.tsx]](file/ui-web-admin/src/app/dashboard)/system/roles/page.tsx) - [[ui-web-admin/src/app/(dashboard)/system/menus/page.tsx]](file/ui-web-admin/src/app/dashboard)/system/menus/page.tsx) - [[ui-web-admin/src/app/(dashboard)/system/configs/page.tsx]](file/ui-web-admin/src/app/dashboard)/system/configs/page.tsx) - [[ui-web-admin/src/app/(dashboard)/system/departments/page.tsx]](file/ui-web-admin/src/app/dashboard)/system/departments/page.tsx) - [[ui-web-admin/src/app/(dashboard)/system/dicts/page.tsx]](file/ui-web-admin/src/app/dashboard)/system/dicts/page.tsx) - [[ui-web-admin/src/app/(dashboard)/system/logs/page.tsx]](file/ui-web-admin/src/app/dashboard)/system/logs/page.tsx) - [[ui-web-admin/src/app/(dashboard)/cms/news/page.tsx]](file/ui-web-admin/src/app/dashboard)/cms/news/page.tsx) - [[ui-web-admin/src/app/(dashboard)/cms/news/[id]/page.tsx]](file/ui-web-admin/src/app/dashboard)/cms/news/[id]/page.tsx) - [[ui-web-admin/src/app/(dashboard)/cms/news/new/page.tsx]](file/ui-web-admin/src/app/dashboard)/cms/news/new/page.tsx) - [[ui-web-admin/src/app/(dashboard)/dashboard/page.tsx]](file/ui-web-admin/src/app/dashboard)/dashboard/page.tsx) - [[ui-web-top/src/i18n/routing.ts]](file/ui-web-top/src/i18n/routing.ts) - [[ui-web-top/src/middleware.ts]](file/ui-web-top/src/middleware.ts)

Table of Contents ​

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction ​

This document describes the Navigation and Routing system built on Next.js 16 App Router across three applications: ui-web, ui-web-admin, and ui-web-top. It explains the hierarchical navigation structure, sidebar organization, breadcrumb implementation approaches, routing patterns for tenant contexts, dynamic route generation, and navigation state management. It also covers authentication-aware routing, permission-based navigation visibility, and integration with ui-web-top’s internationalization middleware and portal components.

Project Structure ​

The navigation and routing are implemented per application:

  • ui-web: Single-page application layout with a global root layout wrapping a shared AppLayout component.
  • ui-web-admin: Multi-section admin application with a dashboard layout that includes a collapsible sidebar menu, nested routes under (dashboard), and dedicated login and CMS routes.
  • ui-web-top: Internationalized marketing website with locale-based routing and middleware-driven locale detection.

Diagram sources

Section sources

Core Components ​

  • Root layouts define global HTML metadata, fonts, and wrappers:
    • ui-web root layout wraps children with AppLayout and injects iconfont styles.
    • ui-web-admin root layout initializes Arco Design CSS and compatibility wrapper, sets metadata, and injects theme initialization script.
  • ui-web-admin dashboard layout implements:
    • Collapsible sidebar with Arco Design Menu and SubMenu.
    • Dynamic open keys based on current pathname.
    • User dropdown with profile modal and logout.
    • Theme toggle persisted in localStorage.
    • Authentication guard via token presence and user info fetching.
  • ui-web-top implements:
    • Locale-based routing via [locale] dynamic segments.
    • Middleware-driven locale detection and redirects.
    • Internationalization plugin configuration.

Section sources

Architecture Overview ​

The routing architecture leverages Next.js App Router conventions:

  • ui-web: A single-root layout with nested pages under src/app/dashboard, organization, settings, and others.
  • ui-web-admin: A root layout plus a (dashboard) group containing nested routes for tenants, system, and CMS sections. Login is separate.
  • ui-web-top: A root layout with [locale] dynamic segment and middleware-driven locale routing.

Diagram sources

Detailed Component Analysis ​

ui-web-admin Dashboard Layout and Sidebar Navigation ​

The dashboard layout composes:

  • A collapsible Sider with a Menu and SubMenus for Tenants, System, and CMS.
  • A Header with theme toggle and user dropdown.
  • A Content area rendering child routes.
  • Authentication guard checking token and fetching user info; redirects to login if missing or on error.
  • Dynamic open keys derived from the current pathname to keep the correct submenu expanded.

Diagram sources

Key navigation patterns:

  • Sidebar menu items map to absolute paths under (dashboard).
  • Submenu keys are used to expand the correct section based on the current route.
  • Theme persistence is handled via localStorage and DOM attributes.

Section sources

Tenant Context Routing ​

Tenant-related routes are organized under (dashboard)/tenants with nested pages:

  • Tenants list
  • Packages list
  • Menus management

These routes demonstrate:

  • Group-based routing via parentheses in the folder name.
  • Nested dynamic segments for editing and creation flows (e.g., [id]).

Diagram sources

Section sources

System Management and Permission-Based Visibility ​

System routes include:

  • Menus
  • Configs
  • Departments
  • Roles
  • Users
  • Dicts
  • Logs

These routes illustrate:

  • Hierarchical grouping under the System submenu.
  • Potential for permission-based visibility by conditionally rendering menu items based on user roles.

Diagram sources

Section sources

ui-web-top Internationalization and Locale Routing ​

ui-web-top supports locale-based routing:

  • Dynamic segment [locale] under src/app enables routes like /en, /zh.
  • Middleware detects the user’s preferred locale and redirects accordingly.
  • next-intl plugin is configured in next.config.ts to enable internationalization features.

Diagram sources

Section sources

Authentication-Aware Routing and State Management ​

  • ui-web-admin guards protected routes by checking for a token and fetching user info. On failure, it redirects to /login.
  • Navigation state includes:
    • Sidebar collapse state
    • Theme selection (light/dark)
    • User info and profile modal visibility
    • Current pathname for menu selection and open keys

Diagram sources

Section sources

While explicit breadcrumb components are not present in the analyzed files, common Next.js App Router patterns include:

  • Generating breadcrumbs from the pathname segments.
  • Using metadata or a helper to map route segments to human-readable labels.
  • Rendering breadcrumbs in a layout that wraps page content.

This section provides conceptual guidance; no specific file analysis is included here.

[No sources needed since this section doesn't analyze specific source files]

Dynamic Route Generation and Parameter Handling ​

Dynamic routes are used for:

  • Editing existing records: [id] under CMS news
  • Locale handling: [locale] under ui-web-top

These patterns enable:

  • Parameter extraction in page components
  • Conditional rendering based on parameters
  • Consistent URL structures for CRUD operations

Section sources

Custom Navigation Components and Transition Handling ​

  • The dashboard layout demonstrates a reusable navigation component (Arco Design Menu/SubMenu) with:
    • Click handlers for programmatic navigation
    • Dynamic open keys based on pathname
    • Persistent theme and user state
  • Route transitions are handled by Next Router; no custom transition library is configured in the analyzed files.

Section sources

Dependency Analysis ​

  • ui-web depends on a shared AppLayout wrapper defined outside the provided snippet.
  • ui-web-admin depends on:
    • Arco Design components for layout and menu
    • authApi for user info and logout
    • Next Router for navigation
  • ui-web-top depends on:
    • next-intl plugin
    • Middleware for locale detection
    • i18n routing configuration

Diagram sources

Section sources

Performance Considerations ​

  • ui-web forces dynamic rendering at the root level, which ensures fresh data but may increase server-side load.
  • ui-web-admin uses a dashboard layout with local state for theme and sidebar; keep state minimal and avoid unnecessary re-renders.
  • ui-web-top middleware performs locale detection; ensure it is efficient and caches decisions when appropriate.

[No sources needed since this section provides general guidance]

Troubleshooting Guide ​

Common issues and resolutions:

  • Authentication failures: If user info fetch fails, the layout redirects to /login. Verify token storage and authApi endpoint availability.
  • Sidebar not expanding: Ensure the current pathname matches the expected prefix so getOpenKeys returns the correct submenu key.
  • Theme not persisting: Confirm localStorage key usage and DOM attribute setting for arco-theme.
  • Locale redirects loop: Verify middleware logic and routing configuration to prevent infinite redirects.

Section sources

Conclusion ​

The navigation and routing system across ui-web, ui-web-admin, and ui-web-top leverages Next.js 16 App Router effectively:

  • ui-web-admin provides a robust, authenticated dashboard with a collapsible sidebar, grouped routes, and persistent state.
  • ui-web-top integrates internationalization with locale-based routing and middleware-driven redirection.
  • Dynamic routes support flexible editing and creation flows.
  • Authentication-aware routing and permission-based navigation visibility can be implemented by extending menu rendering logic with role checks.