tokens-reef/frontend/src/router

Vue Router Configuration

Overview

This directory contains the Vue Router configuration for the Sub2API frontend application. The router implements a comprehensive navigation system with authentication guards, role-based access control, and lazy loading.

Files

• index.ts: Main router configuration with route definitions and navigation guards
• meta.d.ts: TypeScript type definitions for route meta fields

Route Structure

Public Routes (No Authentication Required)

Path	Component	Description
/login	LoginView	User login page
/register	RegisterView	User registration page

User Routes (Authentication Required)

Path	Component	Description
/	-	Redirects to /dashboard
/dashboard	DashboardView	User dashboard with stats
/keys	KeysView	API key management
/usage	UsageView	Usage records and statistics
/redeem	RedeemView	Redeem code interface
/profile	ProfileView	User profile settings

Admin Routes (Admin Role Required)

Path	Component	Description
/admin	-	Redirects to /admin/dashboard
/admin/dashboard	AdminDashboardView	Admin dashboard
/admin/users	AdminUsersView	User management
/admin/groups	AdminGroupsView	Group management
/admin/accounts	AdminAccountsView	Account management
/admin/proxies	AdminProxiesView	Proxy management
/admin/redeem	AdminRedeemView	Redeem code management

Special Routes

Path	Component	Description
/:pathMatch(.*)	NotFoundView	404 error page

Navigation Guards

Authentication Guard (beforeEach)

The router implements a comprehensive navigation guard that:

1. Sets Page Title: Updates document title based on route meta
2. Checks Authentication:
   • Public routes (requiresAuth: false) are accessible without login
   • Protected routes require authentication
   • Redirects to /login if not authenticated
3. Prevents Double Login:
   • Redirects authenticated users away from login/register pages
4. Role-Based Access Control:
   • Admin routes (requiresAdmin: true) require admin role
   • Non-admin users are redirected to /dashboard
5. Preserves Intended Destination:
   • Saves original URL in query parameter for post-login redirect

Flow Diagram

User navigates to route
        ↓
Set page title from meta
        ↓
Is route public? ──Yes──→ Already authenticated? ──Yes──→ Redirect to /dashboard
        ↓ No                                        ↓ No
        ↓                                      Allow access
        ↓
Is user authenticated? ──No──→ Redirect to /login with redirect query
        ↓ Yes
        ↓
Requires admin role? ──Yes──→ Is user admin? ──No──→ Redirect to /dashboard
        ↓ No                                  ↓ Yes
        ↓                                     ↓
Allow access ←────────────────────────────────┘

Route Meta Fields

Each route can define the following meta fields:

interface RouteMeta {
  requiresAuth?: boolean // Default: true (requires authentication)
  requiresAdmin?: boolean // Default: false (admin access only)
  title?: string // Page title
  breadcrumbs?: Array<{
    // Breadcrumb navigation
    label: string
    to?: string
  }>
  icon?: string // Icon for navigation menu
  hideInMenu?: boolean // Hide from navigation menu
}

Lazy Loading

All route components use dynamic imports for code splitting:

component: () => import('@/views/user/DashboardView.vue')

Benefits:

• Reduced initial bundle size
• Faster initial page load
• Components loaded on-demand
• Automatic code splitting by Vite

Authentication Store Integration

The router integrates with the Pinia auth store (@/stores/auth):

const authStore = useAuthStore()

// Check authentication status
authStore.isAuthenticated

// Check admin role
authStore.isAdmin

Usage Examples

Programmatic Navigation

import { useRouter } from 'vue-router'

const router = useRouter()

// Navigate to a route
router.push('/dashboard')

// Navigate with query parameters
router.push({
  path: '/usage',
  query: { filter: 'today' }
})

// Navigate to admin route (will be blocked if not admin)
router.push('/admin/users')

Route Links

<template>
  <!-- Simple link -->
  <router-link to="/dashboard">Dashboard</router-link>

  <!-- Named route -->
  <router-link :to="{ name: 'Keys' }">API Keys</router-link>

  <!-- With query parameters -->
  <router-link :to="{ path: '/usage', query: { page: 1 } }"> Usage </router-link>
</template>

Checking Current Route

import { useRoute } from 'vue-router'

const route = useRoute()

// Check if on admin page
const isAdminPage = route.path.startsWith('/admin')

// Get route meta
const requiresAdmin = route.meta.requiresAdmin

Scroll Behavior

The router implements automatic scroll management:

• Browser Navigation: Restores saved scroll position
• New Routes: Scrolls to top of page
• Hash Links: Scrolls to anchor (when implemented)

Error Handling

The router includes error handling for navigation failures:

router.onError((error) => {
  console.error('Router error:', error)
})

Testing Routes

To test navigation guards and route access:

1. Public Route Access: Visit /login without authentication
2. Protected Route: Try accessing /dashboard without login (should redirect)
3. Admin Access: Login as regular user, try /admin/users (should redirect to dashboard)
4. Admin Success: Login as admin, access /admin/users (should succeed)
5. 404 Handling: Visit non-existent route (should show 404 page)

Development Tips

Adding New Routes

1. Add route definition in routes array
2. Create corresponding view component
3. Set appropriate meta fields (requiresAuth, requiresAdmin)
4. Use lazy loading with () => import()
5. Update this README with route documentation

Debugging Navigation

Enable Vue Router debug mode:

// In browser console
window.__VUE_ROUTER__ = router

// Check current route
router.currentRoute.value

Common Issues

Issue: 404 on page refresh

• Cause: Server not configured for SPA
• Solution: Configure server to serve index.html for all routes

Issue: Navigation guard runs twice

• Cause: Multiple next() calls
• Solution: Ensure only one next() call per code path

Issue: User data not loaded

• Cause: Auth store not initialized
• Solution: Call authStore.checkAuth() in App.vue or main.ts

Security Considerations

1. Client-Side Only: Navigation guards are client-side; server must also validate
2. Token Validation: API should verify JWT token on every request
3. Role Checking: Backend must verify admin role, not just frontend
4. XSS Protection: Vue automatically escapes template content
5. CSRF Protection: Use CSRF tokens for state-changing operations

Performance Optimization

1. Lazy Loading: All routes use dynamic imports
2. Code Splitting: Vite automatically splits route chunks
3. Prefetching: Consider adding route prefetch for common paths
4. Route Caching: Vue Router caches component instances

Future Enhancements

• Add breadcrumb navigation system
• Implement route-based permissions beyond admin/user
• Add route transition animations
• Implement route prefetching for anticipated navigation
• Add navigation analytics tracking