Fix: Same-Route Navigation Causes Page Flash and Metadata Flicker (Next.js 16 App Router + basePath)

Problem

When clicking a <Link> that points to the current active route, Next.js 16 App Router incorrectly triggers a navigation event instead of a no-op. This causes:

• A brief flash of unrelated page content (served from router cache)
• Incorrect metadata rendered during the flash
• A full client-side navigation cycle on an already-active route

This behavior is only present when basePath is configured in next.config.js. Removing basePath resolves the issue.

Root Cause

The router cache key resolution does not correctly account for basePath when comparing the current route against the target href. As a result:

• pathname === href evaluates to false (path mismatch due to basePath prefix)
• Navigation proceeds instead of being suppressed
• A stale cache entry for a different route is momentarily rendered before the correct page re-hydrates

Workaround

Option 1: Suppress navigation when already on the same route (Recommended)

Wrap <Link> with an onClick guard that prevents re-navigation:

"use client"

import Link from "next/link"
import { usePathname } from "next/navigation"

interface SafeLinkProps extends React.ComponentProps<typeof Link> {
  href: string
}

export function SafeLink({ href, children, onClick, ...props }: SafeLinkProps) {
  const pathname = usePathname()

  const handleClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
    if (pathname === href) {
      e.preventDefault()
      return
    }
    onClick?.(e)
  }

  return (
    <Link href={href} onClick={handleClick} {...props}>
      {children}
    </Link>
  )
}

Replace <Link> with <SafeLink> in your category nav:

// Before
<Link href="/menu/pizza">Pizza</Link>

// After
<SafeLink href="/menu/pizza">Pizza</SafeLink>

Option 2: Disable router cache for affected segments

In the affected page or layout, opt out of client-side caching to prevent stale cache entries from flashing:

// app/menu/[category]/page.tsx
export const dynamic = "force-dynamic"

Note: This increases server load — use only on pages where the flash is most visible.

Option 3: Stabilize metadata with generateMetadata

Prevent metadata from flickering during the flash by ensuring it resolves server-side:

// app/menu/[category]/page.tsx
export async function generateMetadata({
  params,
}: {
  params: { category: string }
}) {
  return {
    title: `${params.category} — Menu`,
  }
}

Avoid deriving metadata client-side (e.g. in useEffect) as it will update after hydration and contribute to the flicker.

Option 4: Remove or scope basePath (if feasible)

If basePath is not strictly required, removing it eliminates the root cause entirely:

// next.config.js
module.exports = {
  // basePath: "/app",  // remove or scope to non-affected routes
}

Verification

After applying Option 1:

1. Navigate to /menu/pizza
2. Click the Pizza link again
3. Confirm:
   • No page flash occurs
   • Metadata remains stable
   • Network tab shows no new navigation request

Environment

References

• Demo: https://v0-ecommerce-next-js-app.vercel.app/menu
• Repo: https://github.com/alexismendez11/ecommerce-demo
• Related: Next.js router cache key resolution with basePath

Suggested Upstream Fix

The router's same-route detection logic should strip basePath before comparing pathname to the target href, consistent with how usePathname() already returns the path without the basePath prefix.