fix: preserve library params in docs links

tannerlinsley · tannerlinsley · commit 86792c8c573b · 2026-04-11T20:55:20.000-06:00
Pass library and version params explicitly in landing and docs navigation links so static landing routes resolve the right destinations. This avoids undefined home/docs URLs after the landing route split.
diff --git a/src/components/BackgroundGradient.tsx b/src/components/BackgroundGradient.tsx
@@ -1,21 +1,19 @@
 import { twMerge } from 'tailwind-merge'
-import { useMatches, useParams } from '@tanstack/react-router'
+import { useLocation, useParams } from '@tanstack/react-router'
 import { findLibrary } from '~/libraries'
 
 export function BackgroundGradient() {
   let libraryId = useParams({
     select: (p) => p.libraryId,
     strict: false,
   }) as string
-
-  const matches = useMatches()
+  const location = useLocation()
 
   if (!libraryId) {
-    const matchIndex = matches.findIndex((m) => m.routeId === '/_libraries')
-    const match = matches[matchIndex + 1]
-    if (match) {
-      // Route ID format: /_libraries/query/$version/ -> split gives ['', '_libraries', 'query', '$version', '']
-      libraryId = match.routeId.split('/')[2]
+    const pathnameLibraryId = location.pathname.split('/')[1]
+
+    if (pathnameLibraryId) {
+      libraryId = pathnameLibraryId
     }
   }
 
diff --git a/src/components/DocsLayout.tsx b/src/components/DocsLayout.tsx
@@ -341,6 +341,8 @@ export const useWidthToggle = () => {
 // Create context for doc navigation (prev/next)
 type DocNavItem = { label: React.ReactNode; to: string }
 const DocNavigationContext = React.createContext<{
+  libraryId: LibraryId
+  version: string
   prevItem?: DocNavItem
   nextItem?: DocNavItem
   colorFrom: string
@@ -356,7 +358,15 @@ export function DocNavigation() {
   const context = useDocNavigation()
   if (!context) return null
 
-  const { prevItem, nextItem, colorFrom, colorTo, textColor } = context
+  const {
+    libraryId,
+    version,
+    prevItem,
+    nextItem,
+    colorFrom,
+    colorTo,
+    textColor,
+  } = context
 
   if (!prevItem && !nextItem) return null
 
@@ -368,7 +378,7 @@ export function DocNavigation() {
             as={Link}
             from="/$libraryId/$version/docs"
             to={prevItem.to}
-            params
+            params={{ libraryId, version } as never}
             className="py-1 px-2 sm:py-2 sm:px-3 flex items-center gap-1 sm:gap-2"
           >
             <ChevronLeft className="w-3 h-3 sm:w-4 sm:h-4" />
@@ -387,7 +397,7 @@ export function DocNavigation() {
             as={Link}
             from="/$libraryId/$version/docs"
             to={nextItem.to}
-            params
+            params={{ libraryId, version } as never}
             className="py-1 px-2 sm:py-2 sm:px-3 flex items-center gap-1 sm:gap-2"
           >
             <div className="flex flex-col items-end">
@@ -651,6 +661,10 @@ export function DocsLayout({
         <ul className="text-[.85em] leading-snug list-none">
           {group?.children?.map((child, i) => {
             const linkClasses = `flex gap-2 items-center justify-between group px-2 py-1.5 rounded-lg hover:bg-gray-500/10 opacity-60 hover:opacity-100`
+            const linkParams =
+              !child.to.startsWith('/') || child.to.includes('/$libraryId')
+                ? ({ libraryId, version } as never)
+                : undefined
 
             return (
               <li key={i}>
@@ -667,7 +681,7 @@ export function DocsLayout({
                   <Link
                     from="/$libraryId/$version/docs"
                     to={child.to}
-                    params
+                    params={linkParams}
                     onClick={() => {
                       detailsRef.current.removeAttribute('open')
                     }}
@@ -877,7 +891,15 @@ export function DocsLayout({
   return (
     <WidthToggleContext.Provider value={{ isFullWidth, setIsFullWidth }}>
       <DocNavigationContext.Provider
-        value={{ prevItem, nextItem, colorFrom, colorTo, textColor }}
+        value={{
+          libraryId,
+          version,
+          prevItem,
+          nextItem,
+          colorFrom,
+          colorTo,
+          textColor,
+        }}
       >
         <div
           className={`
diff --git a/src/components/FrameworkCard.tsx b/src/components/FrameworkCard.tsx
@@ -1,6 +1,6 @@
 import { Link } from '@tanstack/react-router'
 import { twMerge } from 'tailwind-merge'
-import { Library } from '~/libraries'
+import type { Library, LibraryId } from '~/libraries'
 import { getFrameworkOptions } from '~/libraries/frameworks'
 import { useCopyButton } from '~/components/CopyMarkdownButton'
 import { useToast } from '~/components/ToastProvider'
@@ -10,12 +10,14 @@ import { Card } from '~/components/Card'
 export function FrameworkCard({
   framework,
   libraryId,
+  version,
   packageName,
   index,
   library,
 }: {
   framework: ReturnType<typeof getFrameworkOptions>[number]
-  libraryId: string
+  libraryId: LibraryId
+  version: string
   packageName: string
   index: number
   library: Library
@@ -62,6 +64,8 @@ export function FrameworkCard({
         from="/$libraryId/$version/docs"
         to="./$"
         params={{
+          libraryId,
+          version,
           _splat: installationPath,
         }}
         hash={installationHash}
@@ -111,6 +115,8 @@ export function FrameworkCard({
           from="/$libraryId/$version/docs"
           to="./$"
           params={{
+            libraryId,
+            version,
             _splat: installationPath,
           }}
           hash={installationHash}
diff --git a/src/components/landing/CliLanding.tsx b/src/components/landing/CliLanding.tsx
@@ -1,4 +1,4 @@
-import { Link } from '@tanstack/react-router'
+import { Link, useParams } from '@tanstack/react-router'
 import { Layers } from 'lucide-react'
 import { Footer } from '~/components/Footer'
 import { LazySponsorSection } from '~/components/LazySponsorSection'
@@ -16,6 +16,8 @@ import { LazyLandingCommunitySection } from '~/components/LazyLandingCommunitySe
 const library = getLibrary('cli')
 
 export default function CliLanding() {
+  const { version } = useParams({ strict: false })
+
   return (
     <LibraryPageContainer>
       <LibraryHero
@@ -32,7 +34,7 @@ export default function CliLanding() {
             </Button>
             <Button
               as="a"
-              href="/cli/latest/docs"
+              href={`/cli/${version}/docs`}
               className="bg-indigo-500 border-indigo-500 hover:bg-indigo-600 dark:bg-indigo-600 dark:border-indigo-600 text-white"
             >
               Get Started
@@ -58,7 +60,7 @@ export default function CliLanding() {
       <BottomCTA
         linkProps={{
           to: '/$libraryId/$version/docs',
-          params: { libraryId: library.id },
+          params: { libraryId: library.id, version },
         }}
         label="Get Started!"
         className="bg-indigo-500 border-indigo-500 hover:bg-indigo-600 text-white"
diff --git a/src/components/landing/ConfigLanding.tsx b/src/components/landing/ConfigLanding.tsx
@@ -1,3 +1,4 @@
+import { useParams } from '@tanstack/react-router'
 import { Footer } from '~/components/Footer'
 import { LazySponsorSection } from '~/components/LazySponsorSection'
 import { LibraryHero } from '~/components/LibraryHero'
@@ -15,14 +16,16 @@ import { LazyLandingCommunitySection } from '~/components/LazyLandingCommunitySe
 const library = getLibrary('config')
 
 export default function ConfigLanding() {
+  const { version } = useParams({ strict: false })
+
   return (
     <LibraryPageContainer>
       <LibraryHero
         project={configProject}
         actions={
           <Button
             as="a"
-            href={`/config/latest/docs`}
+            href={`/config/${version}/docs`}
             className="bg-gray-500 border-gray-500 hover:bg-gray-600 text-white"
           >
             Get Started
@@ -72,7 +75,7 @@ export default function ConfigLanding() {
       <BottomCTA
         linkProps={{
           to: '/$libraryId/$version/docs',
-          params: { libraryId: library.id },
+          params: { libraryId: library.id, version },
         }}
         label="Get Started!"
         className="bg-gray-500 border-gray-500 hover:bg-gray-600 text-white"
diff --git a/src/components/landing/DbLanding.tsx b/src/components/landing/DbLanding.tsx
@@ -1,3 +1,4 @@
+import { useParams } from '@tanstack/react-router'
 import { Footer } from '~/components/Footer'
 import { LazySponsorSection } from '~/components/LazySponsorSection'
 import { BottomCTA } from '~/components/BottomCTA'
@@ -13,14 +14,16 @@ import { LazyLandingCommunitySection } from '~/components/LazyLandingCommunitySe
 const library = getLibrary('db')
 
 export default function DbLanding() {
+  const { version } = useParams({ strict: false })
+
   return (
     <LibraryPageContainer>
       <LibraryHero
         project={dbProject}
         cta={{
           linkProps: {
             to: '/$libraryId/$version/docs',
-            params: { libraryId: library.id },
+            params: { libraryId: library.id, version },
           },
           label: 'Get Started',
           className:
@@ -82,7 +85,7 @@ export default function DbLanding() {
       <BottomCTA
         linkProps={{
           to: '/$libraryId/$version/docs',
-          params: { libraryId: library.id },
+          params: { libraryId: library.id, version },
         }}
         label="Get Started!"
         className="bg-orange-500 border-orange-500 hover:bg-orange-600 text-white"
diff --git a/src/components/landing/DevtoolsLanding.tsx b/src/components/landing/DevtoolsLanding.tsx
@@ -1,3 +1,4 @@
+import { useParams } from '@tanstack/react-router'
 import { Footer } from '~/components/Footer'
 import { LazySponsorSection } from '~/components/LazySponsorSection'
 import { BottomCTA } from '~/components/BottomCTA'
@@ -14,14 +15,16 @@ import { LazyLandingCommunitySection } from '~/components/LazyLandingCommunitySe
 const library = getLibrary('devtools')
 
 export default function DevtoolsLanding() {
+  const { version } = useParams({ strict: false })
+
   return (
     <LibraryPageContainer>
       <LibraryHero
         project={devtoolsProject}
         cta={{
           linkProps: {
             to: '/$libraryId/$version/docs',
-            params: { libraryId: library.id },
+            params: { libraryId: library.id, version },
           },
           label: 'Get Started',
           className:
@@ -74,7 +77,7 @@ export default function DevtoolsLanding() {
       <BottomCTA
         linkProps={{
           to: '/$libraryId/$version/docs',
-          params: { libraryId: library.id },
+          params: { libraryId: library.id, version },
         }}
         label="Get Started!"
         className="bg-slate-500 border-slate-500 hover:bg-slate-600 hover:border-slate-600 text-white"
diff --git a/src/components/landing/HotkeysLanding.tsx b/src/components/landing/HotkeysLanding.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react'
-import { ClientOnly } from '@tanstack/react-router'
+import { ClientOnly, useParams } from '@tanstack/react-router'
 import { Footer } from '~/components/Footer'
 import { LibraryHero } from '~/components/LibraryHero'
 import { LazySponsorSection } from '~/components/LazySponsorSection'
@@ -22,6 +22,8 @@ const LazyHotkeysShortcutBinding = React.lazy(() =>
 )
 
 export default function HotkeysLanding() {
+  const { version } = useParams({ strict: false })
+
   return (
     <LibraryPageContainer>
       <ClientOnly>
@@ -34,7 +36,7 @@ export default function HotkeysLanding() {
         cta={{
           linkProps: {
             to: '/$libraryId/$version/docs',
-            params: { libraryId: library.id, version: 'latest' },
+            params: { libraryId: library.id, version },
           },
           label: (
             <>
@@ -85,7 +87,7 @@ export default function HotkeysLanding() {
       <BottomCTA
         linkProps={{
           to: '/$libraryId/$version/docs',
-          params: { libraryId: library.id },
+          params: { libraryId: library.id, version },
         }}
         label="Get Started!"
         className="bg-rose-600 border-rose-600 hover:bg-rose-700 hover:border-rose-700 text-white"
diff --git a/src/components/landing/IntentLanding.tsx b/src/components/landing/IntentLanding.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react'
-import { Link, useNavigate } from '@tanstack/react-router'
+import { Link, useNavigate, useParams } from '@tanstack/react-router'
 import { useQuery } from '@tanstack/react-query'
 import { Footer } from '~/components/Footer'
 import { LazySponsorSection } from '~/components/LazySponsorSection'
@@ -24,6 +24,8 @@ import type { SkillHistoryEntry } from '~/utils/intent.functions'
 const library = getLibrary('intent')
 
 export default function IntentLanding() {
+  const { version } = useParams({ strict: false })
+
   return (
     <LibraryPageContainer>
       <LibraryHero
@@ -39,9 +41,8 @@ export default function IntentLanding() {
             </Button>
             <Button
               as={Link}
-              from="/$libraryId/$version"
-              to="./docs"
-              params={{ libraryId: library.id } as never}
+              to="/$libraryId/$version/docs"
+              params={{ libraryId: library.id, version } as never}
               className="bg-sky-500 border-sky-500 hover:bg-sky-600 dark:bg-sky-600 dark:border-sky-600 text-white"
             >
               Get Started
@@ -69,7 +70,7 @@ export default function IntentLanding() {
       <BottomCTA
         linkProps={{
           to: '/$libraryId/$version/docs',
-          params: { libraryId: library.id },
+          params: { libraryId: library.id, version },
         }}
         label="Get Started!"
         className="bg-sky-500 border-sky-500 hover:bg-sky-600 text-white"
diff --git a/src/components/landing/PacerLanding.tsx b/src/components/landing/PacerLanding.tsx
@@ -1,3 +1,4 @@
+import { useParams } from '@tanstack/react-router'
 import { Footer } from '~/components/Footer'
 import { LibraryHero } from '~/components/LibraryHero'
 import { LazySponsorSection } from '~/components/LazySponsorSection'
@@ -14,14 +15,16 @@ import { LazyLandingCommunitySection } from '~/components/LazyLandingCommunitySe
 const library = getLibrary('pacer')
 
 export default function PacerLanding() {
+  const { version } = useParams({ strict: false })
+
   return (
     <LibraryPageContainer>
       <LibraryHero
         project={pacerProject}
         cta={{
           linkProps: {
             to: '/$libraryId/$version/docs',
-            params: { libraryId: library.id },
+            params: { libraryId: library.id, version },
           },
           label: 'Get Started',
           className: 'bg-lime-600 border-lime-600 hover:bg-lime-700 text-white',
@@ -72,7 +75,7 @@ export default function PacerLanding() {
       <BottomCTA
         linkProps={{
           to: '/$libraryId/$version/docs',
-          params: { libraryId: library.id },
+          params: { libraryId: library.id, version },
         }}
         label="Get Started!"
         className="bg-lime-600 border-lime-600 hover:bg-lime-700 hover:border-lime-700 text-white"
diff --git a/src/components/landing/StartLanding.tsx b/src/components/landing/StartLanding.tsx
diff --git a/src/components/landing/StoreLanding.tsx b/src/components/landing/StoreLanding.tsx
diff --git a/src/routes/$libraryId/$version.docs.framework.index.tsx b/src/routes/$libraryId/$version.docs.framework.index.tsx
