Routing

App Router Architecture

Horse Trust uses Next.js 16’s App Router, which provides file-system based routing with enhanced features like layouts, server components, and streaming.

Route Structure

app/
├── layout.tsx                    # Root layout (wraps all pages)
├── page.tsx                      # Homepage → /
├── actions/                      # Server Actions
│   ├── auth.ts                  # Authentication server actions
│   └── horses.ts                # Horse management actions
├── dashboard/
│   └── page.tsx                 # Dashboard → /dashboard
├── login/
│   └── page.tsx                 # Login → /login
├── marketplace/
│   ├── page.tsx                 # Marketplace listing → /marketplace
│   └── [id]/
│       └── page.tsx             # Horse detail → /marketplace/[id]
├── registro/
│   └── page.tsx                 # User registration → /registro
├── registro-caballo/
│   ├── page.tsx                 # Horse registration → /registro-caballo
│   └── RegistroCaballoForm.tsx  # Form component
└── utils/
    └── apiFetch.ts              # API utility functions

Root Layout

The root layout wraps all pages and provides global UI elements. Location: app/layout.tsx

app/layout.tsx

import type { Metadata } from "next";
import "./globals.css";
import Header from "@/component/layout/Header";
import Footer from "@/component/layout/Footer";
import { cookies } from 'next/headers';

export const metadata: Metadata = {
  title: "HorseTrust | Mercado de Caballos de Élite Verificados",
  description: "La plataforma líder para la compra y venta de caballos de alto valor.",
};

export default async function RootLayout({
  children,
}: { children: React.ReactNode }) {
  const cookieStore = await cookies();
  const isLoggedIn = cookieStore.has('horse_trust_token');
  
  return (
    <html lang="en">
      <body>
        <Header initialIsLoggedIn={isLoggedIn}/>
        {children}
        <Footer/>
      </body>
    </html>
  );
}

Key Features:

Server Component: Runs on the server for optimal performance
Cookie Access: Reads authentication state from cookies
Metadata Export: Sets page title and description for SEO
Global Components: Header and Footer included in all pages

Public Routes

Homepage

Route: / File: app/page.tsx

app/page.tsx

import HeroSection from '@/component/home/HeroSection';
import FeaturedHorses from '@/component/home/FeaturedHorses';
import SecuritySection from '@/component/home/SecuritySection';

export default function LandingPage() {
  return (
    <div className="bg-background-light min-h-screen">
      <main>
        <HeroSection />
        <FeaturedHorses />
        <SecuritySection />
      </main>
    </div>
  );
}

Marketplace Listing

Route: /marketplace File: app/marketplace/page.tsx

app/marketplace/page.tsx

import MarketplaceClient from '@/component/marketplace/MarketplaceClient';

export const dynamic = 'force-dynamic';

async function getHorses() {
  try {
    const apiUrl = process.env.NEXT_PUBLIC_API_URL;
    const res = await fetch(`${apiUrl}/horses`, {
      next: { revalidate: 60 } 
    });

    if (!res.ok) throw new Error('Error al traer los caballos');

    const jsonResponse = await res.json();
    const horsesArray = Array.isArray(jsonResponse) ? jsonResponse : jsonResponse.data;

    return horsesArray;
  } catch (error) {
    console.error("Error:", error);
    return []; 
  }
}

export default async function MarketplacePage() {
  const initialHorses = await getHorses();
  return <MarketplaceClient initialHorses={initialHorses} />;
}

Features:

Server-side data fetching
Dynamic rendering with force-dynamic
Revalidation every 60 seconds
Error handling for API failures

Dynamic Routes

Horse Detail Page

Route: /marketplace/[id] File: app/marketplace/[id]/page.tsx URL Example: /marketplace/123 Dynamic routes use folder names with square brackets to create parameterized URLs:

export default async function HorseDetailPage({ 
  params 
}: { 
  params: { id: string } 
}) {
  const { id } = params;
  
  // Fetch horse data using id
  const horse = await fetchHorseById(id);
  
  return (
    <div>
      <h1>{horse.name}</h1>
      {/* Horse details */}
    </div>
  );
}

Dynamic Segment Access:

params.id contains the dynamic segment value
Type-safe with TypeScript
Can be used for data fetching

Authentication Routes

Route: /login File: app/login/page.tsx Type: Client Component

app/login/page.tsx

"use client";
import { useState } from 'react';
import { useRouter } from 'next/navigation';
import { loginUser } from '@/app/actions/auth';

export default function LoginPage() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [isLoading, setIsLoading] = useState(false);
  const router = useRouter();

  const handleLogin = async (e: React.FormEvent) => {
    e.preventDefault();
    setIsLoading(true);

    const response = await loginUser(email, password);

    if (!response.success) {
      setError(response.error);
      setIsLoading(false);
      return;
    }

    localStorage.setItem('horse_trust_token', response.data.token);
    router.push('/dashboard');
  };

  return (
    <div className="flex min-h-screen">
      <form onSubmit={handleLogin}>
        <input 
          type="email" 
          value={email}
          onChange={(e) => setEmail(e.target.value)}
        />
        <input 
          type="password" 
          value={password}
          onChange={(e) => setPassword(e.target.value)}
        />
        <button type="submit" disabled={isLoading}>
          {isLoading ? 'Verificando...' : 'Ingresar'}
        </button>
      </form>
    </div>
  );
}

Registration Page

Route: /registro File: app/registro/page.tsx Purpose: New user registration

Protected Routes

Dashboard

Route: /dashboard File: app/dashboard/page.tsx Access: Requires authentication

app/dashboard/page.tsx

import { cookies } from 'next/headers';
import { redirect } from 'next/navigation';

export const dynamic = 'force-dynamic';

async function fetchDashboardData(token: string) {
  const apiUrl = process.env.NEXT_PUBLIC_API_URL;
  
  const meRes = await fetch(`${apiUrl}/auth/me`, {
    headers: { 'Authorization': `Bearer ${token}` },
    cache: 'no-store'
  });
  
  const user = await meRes.json();
  return { user };
}

export default async function DashboardPage() {
  const cookieStore = await cookies();
  const tokenCookie = cookieStore.get('horse_trust_token');

  // Redirect to login if not authenticated
  if (!tokenCookie?.value) {
    redirect('/login');
  }

  const data = await fetchDashboardData(tokenCookie.value);
  if (!data) redirect('/login');

  return (
    <div className="min-h-screen">
      <h1>Bienvenida, {data.user.full_name}</h1>
      {/* Dashboard content */}
    </div>
  );
}

Protection Strategy:

Read authentication cookie
If cookie missing, redirect to /login
Validate token with API
If invalid, redirect to /login
Render protected content

Server Actions

Server Actions provide secure server-side mutations from client components. Location: app/actions/auth.ts

app/actions/auth.ts

"use server";
import { cookies } from 'next/headers';
import { redirect } from 'next/navigation';
import { apiFetch } from '../utils/apiFetch';

export async function loginUser(email: string, password: string) {
  try {
    const res = await apiFetch('/auth/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, password }),
    });

    const data = await res.json();

    if (!res.ok) {
      throw new Error(data.error || 'Error al validar credenciales');
    }
    
    const cookieStore = await cookies();
    cookieStore.set('horse_trust_token', data.token, { 
      httpOnly: true, 
      secure: process.env.NODE_ENV === 'production',
      maxAge: 60 * 60 * 24 * 7,
      path: '/',
    });

    return { success: true, data };
  } catch (error: any) {
    return { success: false, error: error.message };
  }
}

export async function logout() {
  const cookieStore = await cookies();
  cookieStore.delete('horse_trust_token');
  redirect('/'); 
}

Usage in Client Component:

import { loginUser, logout } from '@/app/actions/auth';

// In component
const response = await loginUser(email, password);

// Or for logout
await logout();

Link Component

Use Next.js Link for client-side navigation:

import Link from 'next/link';

<Link href="/marketplace" className="...">
  Ver Catálogo
</Link>

Use useRouter in client components:

import { useRouter } from 'next/navigation';

const router = useRouter();

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

// Go back
router.back();

// Refresh current route
router.refresh();

Server-Side Redirects

Use redirect in server components:

import { redirect } from 'next/navigation';

if (!isAuthenticated) {
  redirect('/login');
}

Route Configuration

Dynamic Rendering

Force dynamic rendering for pages that need real-time data:

export const dynamic = 'force-dynamic';

Revalidation

Set revalidation time for data fetching:

fetch(url, {
  next: { revalidate: 60 } // Revalidate every 60 seconds
});

No Cache

Disable caching for sensitive data:

fetch(url, {
  cache: 'no-store'
});

Path Aliases

TypeScript path aliases configured in tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"]
    }
  }
}

Usage:

import Header from '@/component/layout/Header';
import { loginUser } from '@/app/actions/auth';

Middleware (Future Enhancement)

Middleware can be added at middleware.ts for route protection:

middleware.ts

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const token = request.cookies.get('horse_trust_token');
  
  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
  
  return NextResponse.next();
}

export const config = {
  matcher: ['/dashboard/:path*', '/mis-publicaciones/:path*']
};

Route Groups (Optional Pattern)

Route groups can organize routes without affecting URL structure:

app/
├── (auth)/
│   ├── login/
│   └── registro/
└── (dashboard)/
    ├── dashboard/
    └── mis-publicaciones/

This creates shared layouts without adding route segments.

Getting Started

Core Features

Frontend

Backend

Deployment

Contributing

App Router Architecture

Route Structure

Root Layout

Key Features:

Public Routes

Homepage

Marketplace Listing

Dynamic Routes

Horse Detail Page

Authentication Routes

Registration Page

Protected Routes

Dashboard

Server Actions

Navigation Patterns

Link Component

Programmatic Navigation

Server-Side Redirects

Route Configuration

Dynamic Rendering

Revalidation

No Cache

Path Aliases

Middleware (Future Enhancement)

Route Groups (Optional Pattern)

Build docs developers (and LLMs) love

Getting Started

Core Features

Frontend

Backend

Deployment

Contributing

​App Router Architecture

​Route Structure

​Root Layout

​Key Features:

​Public Routes

​Homepage

​Marketplace Listing

​Dynamic Routes

​Horse Detail Page

​Authentication Routes

​Login Page

​Registration Page

​Protected Routes

​Dashboard

​Server Actions

​Navigation Patterns

​Link Component

​Programmatic Navigation

​Server-Side Redirects

​Route Configuration

​Dynamic Rendering

​Revalidation

​No Cache

​Path Aliases

​Middleware (Future Enhancement)

​Route Groups (Optional Pattern)

Build docs developers (and LLMs) love

App Router Architecture

Route Structure

Root Layout

Key Features:

Public Routes

Homepage

Marketplace Listing

Dynamic Routes

Horse Detail Page

Authentication Routes

Login Page

Registration Page

Protected Routes

Dashboard

Server Actions

Navigation Patterns

Link Component

Programmatic Navigation

Server-Side Redirects

Route Configuration

Dynamic Rendering

Revalidation

No Cache

Path Aliases

Middleware (Future Enhancement)

Route Groups (Optional Pattern)