Client Navigation & Transitions

1. Navigation Overview

In Dinou, navigating between routes does not trigger a full browser refresh. Instead, Dinou operates as a high-performance single-page application (SPA):

2. The <Link> Component & Prefetching

The primary way to navigate between pages is the <Link> component imported from "dinou". It intercepts click events, prevents hard reloads, and handles background prefetching:

import { Link } from "dinou";

export function NavigationBar() {
  return (
    <nav className="flex gap-4">
      {/* ✅ Type-Safe href: autocompleted in your IDE via DinouRoute */}
      <Link href="/dashboard">Dashboard</Link>

      {/* ✅ Dynamic interpolation typed against registered routes */}
      <Link href={`/blog/${post.slug}`}>Post</Link>

      {/* Disable prefetch for heavy routes or rarely visited pages */}
      <Link href="/analytics" prefetch={false}>
        Analytics
      </Link>

      {/* ❌ TypeScript compile error on invalid/dead links when using type-safe routing */}
      {/* <Link href="/broken-link">Broken</Link> */}
    </nav>
  );
}

3. Programmatic Navigation (useRouter)

To navigate imperatively from event handlers, timers, or form submissions, use the useRouter() hook inside Client Components ("use client"):

"use client";

import { useRouter } from "dinou";

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

  const handleLogin = async () => {
    await loginUser();
    
    // Navigate programmatically
    router.push("/dashboard");
    
    // Or force fresh data after mutation:
    // router.push("/dashboard", { fresh: true });
  };

  return <button onClick={handleLogin}>Log In</button>;
}

4. Client Router Cache & The fresh Prop

To deliver instant page transitions without unnecessary server requests, Dinou features an in-memory Client Router Cache. Understanding how this cache operates is key to knowing when and why to use the fresh prop.

// Ideal for live feeds, stock tickers, or carts
<Link href="/live-feed" fresh>
  Live Feed
</Link>

// Navigate after a mutation to force fresh server data
const handleUpdate = async () => {
  await updateProfile(data);
  router.push("/profile", { fresh: true });
};

5. Route Transitions (useNavigationLoading)

In Dinou, all client-side navigations execute concurrently inside React 19's startTransition. This ensures that the current view remains fully interactive and visible while the target page's Server Components stream in from the server.

To inform users that a transition is occurring behind the scenes, Dinou provides the useNavigationLoading() hook:

"use client";

import { useNavigationLoading } from "dinou";

export function NavigationProgressBar() {
  const isNavigating = useNavigationLoading();

  if (!isNavigating) return null;

  return (
    <div
      role="progressbar"
      aria-label="Page loading"
      className="fixed top-0 left-0 right-0 z-50 h-1 bg-blue-500/20 overflow-hidden pointer-events-none"
    >
      <div className="h-full bg-blue-600 dark:bg-blue-400 animate-pulse w-full transition-all duration-300" />
    </div>
  );
}

6. Relative Routing Rules

Dinou resolves relative navigation paths (such as about, ./about, or ../dashboard) using a Directory-First Convention. This provides intuitive navigation that accurately mirrors your file system.

This rule applies uniformly across all navigation methods, including the <Link> component and programmatic calls like router.push().