Routing - Kimi UI

Routing System

This guide explains the routing system in KimiStores, covering both Next.js and Vite applications with their specific implementation details.

Routing Structure Overview

KimiStores uses different routing approaches based on the framework:

Next.js App Router

For Next.js applications (next-ts and starter-next-ts), routing is implemented via Next.js App Router:

src/
└── app/
    ├── page.tsx           # Home page (/)
    ├── layout.tsx         # Root layout
    ├── about/
    │   └── page.tsx       # About page (/about)
    ├── dashboard/
    │   ├── layout.tsx     # Dashboard layout
    │   ├── page.tsx       # Dashboard index (/dashboard)
    │   └── products/
    │       └── page.tsx   # Products page (/dashboard/products)

App Router uses file-system based routing with special files like page.tsx, layout.tsx, and loading.tsx.

Vite with React Router

For Vite applications (vite-ts and starter-vite-ts), routing is implemented via React Router:

src/
├── routes/
│   ├── index.tsx          # Define routes configuration
│   └── paths.ts           # Define route paths as constants
└── pages/
    ├── HomePage.tsx       # Home page content
    ├── AboutPage.tsx      # About page content
    ├── dashboard/
    │   ├── DashboardPage.tsx     # Dashboard index
    │   └── ProductsPage.tsx      # Products page

React Router uses component-based routing with centralized route configuration in src/routes/index.tsx.

Next.js Routing Implementation

App Router Features

File Conventions: Special files like page.tsx, layout.tsx, and loading.tsx have specific roles.

Nested Layouts: Multiple layouts can be nested for complex UI structures.

Server Components: Pages are React Server Components by default, which can improve performance.

Loading States: Built-in loading UI with loading.tsx files.

Example: Basic Next.js Route Structure

// src/app/dashboard/products/page.tsx
import { Metadata } from 'next';
import ProductsView from 'src/sections/products/view';

export const metadata: Metadata = {
  title: 'Dashboard: Products',
};

export default function ProductsPage() {
  return <ProductsView />;
}

// src/app/dashboard/layout.tsx
import DashboardLayout from 'src/layouts/dashboard';

export default function Layout({ children }: { children: React.ReactNode }) {
  return <DashboardLayout>{children}</DashboardLayout>;
}

Directory Structure Example:

📁 src/app
📄 page.tsx (Home route: /)
📄 layout.tsx (Root layout)
📁 dashboard
📄 page.tsx (Dashboard route: /dashboard)
📄 layout.tsx (Dashboard layout)
📄 loading.tsx (Loading UI for dashboard)
📁 products
📄 page.tsx (Products route: /dashboard/products)

Vite Routing Implementation

React Router Features

Centralized Configuration: Routes are defined in a central configuration file.

Route Guards: Authentication and permission checks are implemented with higher-order components.

Nested Routes: Support for nested routes and layouts.

Path Constants: Route paths are defined as constants for consistency.

Example: Route Configuration

// src/routes/paths.ts
export const paths = {
  // Root paths
  root: '/',
  about: '/about',
  
  // Dashboard paths
  dashboard: {
    root: '/dashboard',
    products: '/dashboard/products',
    customers: '/dashboard/customers',
    orders: '/dashboard/orders',
  },
};

// src/routes/index.tsx
import { lazy, Suspense } from 'react';
import { Navigate, useRoutes } from 'react-router-dom';
import { paths } from './paths';

// Layouts
import DashboardLayout from 'src/layouts/dashboard';

// Guards
import AuthGuard from 'src/auth/guard/auth-guard';
import GuestGuard from 'src/auth/guard/guest-guard';

// Config
import { PATH_AFTER_LOGIN } from 'src/global-config';

// Pages
const HomePage = lazy(() => import('src/pages/HomePage'));
const AboutPage = lazy(() => import('src/pages/AboutPage'));

// Dashboard
const DashboardPage = lazy(() => import('src/pages/dashboard/DashboardPage'));
const ProductsPage = lazy(() => import('src/pages/dashboard/ProductsPage'));

export default function Router() {
  return useRoutes([
    // Home routes
    {
      path: paths.root,
      element: <HomePage />,
    },
    {
      path: paths.about,
      element: <AboutPage />,
    },
    
    // Dashboard routes
    {
      path: paths.dashboard.root,
      element: (
        <AuthGuard>
          <DashboardLayout />
        </AuthGuard>
      ),
      children: [
        { element: <Navigate to={paths.dashboard.root} replace />, index: true },
        { path: paths.dashboard.root, element: <DashboardPage /> },
        { path: paths.dashboard.products, element: <ProductsPage /> },
      ],
    },
    
    // Not found
    {
      path: '*',
      element: <Navigate to="/404" replace />,
    },
  ]);
}

Navigation

Next.js Navigation

// Client-side navigation
import Link from 'next/link';
import { useRouter } from 'next/navigation';

export default function NavExample() {
  const router = useRouter();

  return (
    <>
      {/* Declarative navigation */}
      <Link href="/dashboard">Dashboard</Link>
      
      {/* Programmatic navigation */}
      <button onClick={() => router.push('/dashboard/products')}>
        Go to Products
      </button>
      
      <button onClick={() => router.back()}>
        Go Back
      </button>
    </>
  );
}

Next.js provides Link component for declarative navigation and useRouter hook for programmatic navigation.

React Router Navigation

// Client-side navigation
import { Link, useNavigate } from 'react-router-dom';
import { paths } from 'src/routes/paths';

export default function NavExample() {
  const navigate = useNavigate();

  return (
    <>
      {/* Declarative navigation */}
      <Link to={paths.dashboard.root}>Dashboard</Link>
      
      {/* Programmatic navigation */}
      <button onClick={() => navigate(paths.dashboard.products)}>
        Go to Products
      </button>
      
      <button onClick={() => navigate(-1)}>
        Go Back
      </button>
    </>
  );
}

React Router provides Link component for declarative navigation and useNavigate hook for programmatic navigation.

Best Practices

1. Use Path Constants: Define route paths as constants to avoid typos and make updates easier.

2. Component Organization: Keep page components in src/pages (Vite) or src/app (Next.js).

3. Auth Guards: Use route guards for protected routes that require authentication.

References

Next.js App Router Documentation React Router Documentation Vite Documentation