From f8c9d28f798b8b6067d85f508eee7ca670121612 Mon Sep 17 00:00:00 2001
From: "Ricardo Q. Bazan" <raquirozbazan@gmail.com>
Date: Wed, 20 May 2026 19:15:12 -0500
Subject: [PATCH] fix(docs): use router Link for landing nav to avoid full-page
 reload

Landing links to /docs were plain <a> tags, forcing a full document
navigation on click. In production this also incurred a 307 redirect
from Cloudflare Assets canonicalizing /docs to /docs/, making the
flash visible. Switch internal links to TanStack Router <Link> so the
transition stays client-side, and add the trailing slash so direct
loads skip the 307 as well.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docsite/src/components/landing/close.tsx |  7 ++-
 docsite/src/components/landing/data.ts   |  2 +-
 docsite/src/components/landing/hero.tsx  |  7 ++-
 docsite/src/components/landing/nav.tsx   | 80 +++++++++++++++---------
 4 files changed, 60 insertions(+), 36 deletions(-)

diff --git a/docsite/src/components/landing/close.tsx b/docsite/src/components/landing/close.tsx
index 596e9bb..a06e2da 100644
--- a/docsite/src/components/landing/close.tsx
+++ b/docsite/src/components/landing/close.tsx
@@ -1,3 +1,4 @@
+import { Link } from "@tanstack/react-router";
 import { ArrowRight } from "lucide-react";
 import { GithubIcon } from "#src/components/github-icon.tsx";
 import { LANDING_META } from "./data.ts";
@@ -33,8 +34,8 @@ export function Close() {
             @max-[480px]/dirA:flex-col @max-[480px]/dirA:items-stretch @max-[480px]/dirA:gap-2.5
           "
         >
-          <a
-            href={LANDING_META.docsHref}
+          <Link
+            to={LANDING_META.docsHref}
             className="
               group inline-flex min-w-[168px] items-center justify-center gap-2.5
               rounded-lg border border-landing-accent bg-landing-accent
@@ -44,7 +45,7 @@ export function Close() {
           >
             Read the docs
             <ArrowRight size={16} className="transition-transform group-hover:translate-x-0.5" aria-hidden />
-          </a>
+          </Link>
           <a
             href={LANDING_META.githubUrl}
             target="_blank"
diff --git a/docsite/src/components/landing/data.ts b/docsite/src/components/landing/data.ts
index 9e8f550..8abca84 100644
--- a/docsite/src/components/landing/data.ts
+++ b/docsite/src/components/landing/data.ts
@@ -120,7 +120,7 @@ export const LANDING_META = {
   vlandUrl: "https://variable.land",
   githubUrl: "https://github.com/variableland/env",
   npmUrl: "https://www.npmjs.com/package/@vlandoss/env",
-  docsHref: "/docs",
+  docsHref: "/docs/" as string,
   publishDate: "2026",
 } as const;
 
diff --git a/docsite/src/components/landing/hero.tsx b/docsite/src/components/landing/hero.tsx
index a7660b1..349d7f5 100644
--- a/docsite/src/components/landing/hero.tsx
+++ b/docsite/src/components/landing/hero.tsx
@@ -1,3 +1,4 @@
+import { Link } from "@tanstack/react-router";
 import { ArrowRight, Check, Copy } from "lucide-react";
 import { useState } from "react";
 import { LANDING_META, RUNTIMES } from "./data.ts";
@@ -86,8 +87,8 @@ export function Hero({ snippets }: { snippets: Snippets }) {
             @max-[760px]/dirA:flex-col @max-[760px]/dirA:items-stretch
           "
         >
-          <a
-            href={LANDING_META.docsHref}
+          <Link
+            to={LANDING_META.docsHref}
             className="
               group inline-flex items-center justify-center gap-2.5
               rounded-lg border border-landing-accent bg-landing-accent
@@ -97,7 +98,7 @@ export function Hero({ snippets }: { snippets: Snippets }) {
           >
             Read the docs
             <ArrowRight size={15} className="transition-transform group-hover:translate-x-0.5" aria-hidden />
-          </a>
+          </Link>
           <button
             type="button"
             onClick={onCopy}
diff --git a/docsite/src/components/landing/nav.tsx b/docsite/src/components/landing/nav.tsx
index ef38918..4149ec6 100644
--- a/docsite/src/components/landing/nav.tsx
+++ b/docsite/src/components/landing/nav.tsx
@@ -1,14 +1,17 @@
+import { Link } from "@tanstack/react-router";
 import { Menu, X } from "lucide-react";
 import { useState } from "react";
 import { BrandMark } from "#src/components/brand-mark.tsx";
 import { GithubIcon } from "#src/components/github-icon.tsx";
 import { LANDING_META } from "./data.ts";
 
-const LINKS = [
-  { label: "Docs", href: "/docs" },
-  { label: "API", href: "/docs/api-reference" },
-  { label: "Guides", href: "/docs/guides" },
-  { label: "Changelog", href: `${LANDING_META.githubUrl}/releases` },
+type NavLink = { label: string; href: string; external?: boolean };
+
+const LINKS: readonly NavLink[] = [
+  { label: "Docs", href: "/docs/" },
+  { label: "API", href: "/docs/api-reference/" },
+  { label: "Guides", href: "/docs/guides/" },
+  { label: "Changelog", href: `${LANDING_META.githubUrl}/releases`, external: true },
 ] as const;
 
 export function LandingNav() {
@@ -50,21 +53,30 @@ export function LandingNav() {
           @max-[480px]/dirA:hidden
         "
       >
-        {LINKS.map((link, i) => (
-          <a
-            key={link.label}
-            href={link.href}
-            data-nav-link
-            data-link-index={i}
-            className="
+        {LINKS.map((link, i) => {
+          const className = `
               text-sm text-landing-dim no-underline transition-colors hover:text-landing-text
               @max-[760px]/dirA:data-[link-index='2']:hidden
               @max-[760px]/dirA:data-[link-index='3']:hidden
-            "
-          >
-            {link.label}
-          </a>
-        ))}
+            `;
+          return link.external ? (
+            <a
+              key={link.label}
+              href={link.href}
+              target="_blank"
+              rel="noreferrer"
+              data-nav-link
+              data-link-index={i}
+              className={className}
+            >
+              {link.label}
+            </a>
+          ) : (
+            <Link key={link.label} to={link.href} data-nav-link data-link-index={i} className={className}>
+              {link.label}
+            </Link>
+          );
+        })}
         <a
           href={LANDING_META.githubUrl}
           target="_blank"
@@ -111,21 +123,31 @@ export function LandingNav() {
           @max-[480px]/dirA:flex
         "
       >
-        {LINKS.map((link) => (
-          <a
-            key={link.label}
-            href={link.href}
-            onClick={() => setOpen(false)}
-            className="
+        {LINKS.map((link) => {
+          const className = `
               flex items-center justify-between border-b border-landing-border
               px-1 py-4 text-base tracking-[-0.005em] text-landing-text no-underline
               last:border-b-0
-            "
-          >
-            <span>{link.label}</span>
-            <span className="text-sm text-landing-dim-2">→</span>
-          </a>
-        ))}
+            `;
+          return link.external ? (
+            <a
+              key={link.label}
+              href={link.href}
+              target="_blank"
+              rel="noreferrer"
+              onClick={() => setOpen(false)}
+              className={className}
+            >
+              <span>{link.label}</span>
+              <span className="text-sm text-landing-dim-2">→</span>
+            </a>
+          ) : (
+            <Link key={link.label} to={link.href} onClick={() => setOpen(false)} className={className}>
+              <span>{link.label}</span>
+              <span className="text-sm text-landing-dim-2">→</span>
+            </Link>
+          );
+        })}
         <a
           href={LANDING_META.githubUrl}
           target="_blank"