> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salesive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Frontend Routing

> Understanding manual and automatic routes in Salesive storefronts

## Overview

Salesive storefronts use a hybrid routing model where certain routes are handled by your frontend application, while others are automatically managed by the Salesive platform. This allows you to maintain full control over your product catalog and browsing experience while delegating authentication, checkout, and account management to Salesive.

## Manual Routes

These routes must be implemented in your frontend application with **React Router**. You have complete control over the UI, data fetching, and user experience.

### Home and Products

<ParamField path="/" type="route">
  **Homepage** - Display featured products, banners, and promotional content. Typically shows a curated selection of products using the Products API.
</ParamField>

<ParamField path="/products" type="route">
  **All Products** - List all available products with filtering, sorting, and pagination. Use the `GET /products` endpoint with query parameters for search and filters.
</ParamField>

<ParamField path="/product/[id-or-slug]" type="route">
  **Product Detail** - Display detailed product information, images, variants, pricing, and add-to-cart functionality. Accepts either product ID or URL slug.
</ParamField>

### Categories

<ParamField path="/category" type="route">
  **All Categories** - Display all product categories as a browsable list or grid. Use the Categories API to fetch the category tree.
</ParamField>

<ParamField path="/category/[id-or-slug]" type="route">
  **Category Products** - Show all products within a specific category with filtering options. Accepts either category ID or URL slug.
</ParamField>

## Automatic Routes

These routes are handled by the Salesive platform and **render with Salesive's default theme by default** — your custom theme does not implement them, and any sub-paths (for example `/blog/my-post` or `/orders/123`) are covered too. Link to these paths from your application, but do not implement them yourself — unless you explicitly opt in to [overriding a route](#overriding-an-automatic-route).

The protected paths are:

```text theme={null}
/cart  /blog  /checkout  /account  /orders  /payment  /invoice
/settings  /login  /logout  /privacy-policy  /terms  /about-us  /return-policy
```

### Overriding an automatic route

A theme can opt in to handling one or more automatic routes **itself** instead of using Salesive's default page. Declare the routes you want to own in the **`routeOverrides`** array of your `salesive.config.json`:

```json theme={null}
{
  "name": "my-theme",
  "version": "1.0.0",
  "routeOverrides": ["/blog", "/about-us"]
}
```

When the theme is uploaded, each entry is validated against the automatic-route list above — only those paths can be overridden, and any other value is rejected. For every route you list:

* The platform serves **your** theme for that route instead of the default page.
* The override covers the whole subtree, so declaring `/blog` also hands `/blog/my-post` to your theme.
* You become responsible for implementing the route (and its data fetching) in your app with React Router, exactly like a [manual route](#manual-routes).

<Warning>
  Only override a route when you intend to fully reimplement it. A listed route no longer falls back to Salesive's built-in page, so leaving it unhandled in your app will render nothing.
</Warning>

<Note>
  Overrides belong to the theme that declares them. Routes you do **not** list keep their default behavior, and switching a store back to a theme without the override restores the platform's default page.
</Note>

### Cart and Blog

<ParamField path="/cart" type="automatic">
  **Cart** - The shopper's cart, including quantity, add-on editing, and item selection, served by the platform's default theme.
</ParamField>

<ParamField path="/blog" type="automatic">
  **Blog** - The shop's blog index listing published posts.
</ParamField>

<ParamField path="/blog/[slug]" type="automatic">
  **Blog Post** - A single blog post, resolved by its slug.
</ParamField>

### Checkout and Payment

<ParamField path="/checkout/[orderId]" type="automatic">
  **Checkout Flow** - Shipping address, payment method selection, and order review for a created order. (Service/business orders are non-shippable, so the shipping step is skipped.)
</ParamField>

<ParamField path="/payment" type="automatic">
  **Payment Processing** - Payment gateway integration and transaction processing. Salesive manages payment collection and verification.
</ParamField>

<ParamField path="/invoice" type="automatic">
  **Invoice** - Order invoices and receipts.
</ParamField>

### Account and Orders

<ParamField path="/account" type="automatic">
  **Account Dashboard** - User account overview including profile information, order history, and saved addresses.
</ParamField>

<ParamField path="/settings" type="automatic">
  **Account Settings** - User preferences, notification settings, and account configuration.
</ParamField>

<ParamField path="/orders" type="automatic">
  **Order History** - Complete list of user orders with status tracking.
</ParamField>

<ParamField path="/orders/[orderId]" type="automatic">
  **Order Detail** - A single order with its items and current status.
</ParamField>

<ParamField path="/login" type="automatic">
  **Login** - Customer sign-in and verification.
</ParamField>

<ParamField path="/logout" type="automatic">
  **Logout** - Handles user session termination and redirects to the appropriate page.
</ParamField>

### Legal Pages

<ParamField path="/privacy-policy" type="automatic">
  **Privacy Policy** - Displays your shop's privacy policy configured in the Salesive dashboard.
</ParamField>

<ParamField path="/terms" type="automatic">
  **Terms and Conditions** - Shows your shop's terms and conditions configured in the Salesive dashboard.
</ParamField>

<ParamField path="/about-us" type="automatic">
  **About Us** - Displays information about your business configured in the Salesive dashboard.
</ParamField>

<ParamField path="/return-policy" type="automatic">
  **Return Policy** - Shows your shop's return and refund policy configured in the Salesive dashboard.
</ParamField>

## Implementation Guide

### Setting Up Manual Routes

Use your preferred routing library to implement manual routes. Here's an example with React Router:

```jsx theme={null}
import { BrowserRouter, Routes, Route } from "react-router-dom";
import HomePage from "./pages/Home";
import ProductsPage from "./pages/Products";
import ProductDetailPage from "./pages/ProductDetail";
import CategoriesPage from "./pages/Categories";
import CategoryProductsPage from "./pages/CategoryProducts";

function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<HomePage />} />
        <Route path="/products" element={<ProductsPage />} />
        <Route path="/product/:slug" element={<ProductDetailPage />} />
        <Route path="/category" element={<CategoriesPage />} />
        <Route path="/category/:slug" element={<CategoryProductsPage />} />
      </Routes>
    </BrowserRouter>
  );
}
```

### Linking to Automatic Routes

Link to automatic routes from your application without implementing the pages:

```jsx theme={null}
import { Link } from "react-router-dom";

function Footer() {
  return (
    <footer>
      <nav>
        <Link to="/about-us">About Us</Link>
        <Link to="/privacy-policy">Privacy Policy</Link>
        <Link to="/terms">Terms & Conditions</Link>
        <Link to="/return-policy">Return Policy</Link>
      </nav>
      
      <nav>
        <Link to="/account">My Account</Link>
        <Link to="/orders">Order History</Link>
        <Link to="/settings">Settings</Link>
        <Link to="/logout">Logout</Link>
      </nav>
    </footer>
  );
}
```

### Cart to Checkout Flow

Checkout is keyed to an order, so create the order from the cart first, then send the
shopper to the automatic `/checkout/{orderId}` route:

```jsx theme={null}
import { useNavigate } from "react-router-dom";
import { orders } from "salesive-api-axios";

function CartPage() {
  const navigate = useNavigate();

  const handleCheckout = async () => {
    if (cartItems.length === 0) return;

    // Convert the cart into an order (returns the created order)
    const { data } = await orders.createFromCart({});
    const orderId = data?.data?._id;

    if (orderId) {
      navigate(`/checkout/${orderId}`);
    }
  };

  return (
    <div>
      {/* Cart items display */}
      <button onClick={handleCheckout}>
        Proceed to Checkout
      </button>
    </div>
  );
}
```

## Dynamic Routes

Use React Router path params for your product and category detail pages, and let the
automatic routes fall through to the Salesive platform. A typical organization:

```
src/
├── App.jsx                  # <Routes> for the manual routes below
└── pages/
    ├── Home.jsx             # /
    ├── Products.jsx         # /products
    ├── ProductDetail.jsx    # /product/:slug
    ├── Categories.jsx       # /category
    └── CategoryProducts.jsx # /category/:slug
```

<Note>
  Automatic routes (`/checkout`, `/account`, `/orders`, legal pages, etc.) are handled
  by Salesive's platform — do **not** add React Router routes for them. Just link to
  those paths and the platform serves them.
</Note>

## Best Practices

<CardGroup cols={2}>
  <Card title="SEO Optimization" icon="magnifying-glass">
    Use URL slugs instead of IDs in manual routes for better SEO. Generate slugs from product and category names.
  </Card>

  <Card title="Loading States" icon="spinner">
    Implement skeleton screens and loading indicators in manual routes while fetching data from the API.
  </Card>

  <Card title="Error Handling" icon="circle-exclamation">
    Handle 404 errors gracefully when products or categories are not found. Suggest alternative products or redirect to relevant pages.
  </Card>

  <Card title="Authentication Guards" icon="shield">
    Check authentication status before showing links to automatic routes like `/account` or `/orders`. Use the Auth API to verify user sessions.
  </Card>
</CardGroup>

## Route Protection

Some automatic routes require authentication. Check user authentication status in your frontend:

```jsx theme={null}
import { useEffect, useState } from "react";
import { auth } from "salesive-api-axios";
import { Link } from "react-router-dom";

function Header() {
  const [isAuthenticated, setIsAuthenticated] = useState(false);
  
  useEffect(() => {
    const checkAuth = async () => {
      try {
        // Verify if user has a valid session
        const token = localStorage.getItem("salesive_token");
        setIsAuthenticated(!!token);
      } catch (error) {
        setIsAuthenticated(false);
      }
    };
    checkAuth();
  }, []);
  
  return (
    <header>
      <nav>
        <Link to="/">Home</Link>
        <Link to="/products">Products</Link>
        <Link to="/category">Categories</Link>
        
        {isAuthenticated ? (
          <>
            <Link to="/account">Account</Link>
            <Link to="/orders">Orders</Link>
            <Link to="/logout">Logout</Link>
          </>
        ) : (
          <button onClick={() => window.location.href = "/login"}>
            Login
          </button>
        )}
      </nav>
    </header>
  );
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Store API Reference" icon="code" href="/api-reference/introduction">
    Explore Products, Categories, and Cart endpoints for implementing manual routes.
  </Card>

  <Card title="Salesive API Axios Client" icon="plug" href="https://www.npmjs.com/package/salesive-api-axios">
    Use typed API wrappers for seamless integration with your routing logic.
  </Card>

  <Card title="Development Guide" icon="wrench" href="/development">
    Learn about Salesive dev tools and configuration management.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get started with a complete Salesive storefront setup.
  </Card>
</CardGroup>