TanStack · tannerlinsley · Apr 27, 2026 · Apr 26, 2026 · Apr 26, 2026
diff --git a/src/router.tsx b/src/router.tsx
@@ -78,6 +78,7 @@ declare module '@tanstack/react-router' {
     baseParent?: boolean
     Title?: () => any
     showNavbar?: boolean
+    includeSearchInCanonical?: boolean
   }
 }
 

diff --git a/src/routes/$libraryId/$version.docs.npm-stats.tsx b/src/routes/$libraryId/$version.docs.npm-stats.tsx
@@ -83,6 +83,9 @@ export const Route = createFileRoute('/$libraryId/$version/docs/npm-stats')({
     height: v.fallback(v.optional(v.number(), 400), 400),
   }),
   component: RouteComponent,
+  staticData: {
+    includeSearchInCanonical: true,
+  },
 })
 
 type NpmStatsSearch = {

diff --git a/src/routes/__root.tsx b/src/routes/__root.tsx
@@ -184,8 +184,21 @@ function ShellComponent({ children }: { children: React.ReactNode }) {
     select: (s) => s.location?.pathname || '/',
   })
 
+  const canonicalSearchStr = useRouterState({
+    select: (s) => s.location?.searchStr || '',
+  })
+
+  const includeSearchInCanonical = useMatches({
+    select: (s) =>
+      s.some((d) => d.staticData?.includeSearchInCanonical === true),
+  })
+
   const preferredCanonicalPath = getCanonicalPath(canonicalPath)
-  const pageUrl = canonicalUrl(preferredCanonicalPath ?? canonicalPath)
+  const canonicalSearch = includeSearchInCanonical ? canonicalSearchStr : ''
+  const pageUrl = canonicalUrl(
+    preferredCanonicalPath ?? canonicalPath,
+    canonicalSearch,
+  )
 
   const showDevtools = import.meta.env.DEV && canShowDevtools
 
@@ -199,7 +212,10 @@ function ShellComponent({ children }: { children: React.ReactNode }) {
     <html lang="en" className={htmlClass} suppressHydrationWarning>
       <head>
         {preferredCanonicalPath ? (
-          <link rel="canonical" href={canonicalUrl(preferredCanonicalPath)} />
+          <link
+            rel="canonical"
+            href={canonicalUrl(preferredCanonicalPath, canonicalSearch)}
+          />
         ) : null}
         <meta property="og:url" content={pageUrl} />
         <meta name="twitter:url" content={pageUrl} />

diff --git a/src/routes/builder.index.tsx b/src/routes/builder.index.tsx
@@ -31,6 +31,7 @@ export const Route = createFileRoute('/builder/')({
   validateSearch: builderSearchSchema,
   component: RouteComponent,
   staticData: {
+    includeSearchInCanonical: true,
     Title: () => (
       <Link
         to="/builder"

diff --git a/src/routes/intent/registry/index.tsx b/src/routes/intent/registry/index.tsx
@@ -58,6 +58,9 @@ export const Route = createFileRoute('/intent/registry/')({
     }),
   }),
   component: IntentRegistryPage,
+  staticData: {
+    includeSearchInCanonical: true,
+  },
 })
 
 function IntentRegistryPage() {

diff --git a/src/routes/maintainers.tsx b/src/routes/maintainers.tsx
@@ -35,6 +35,9 @@ const searchSchema = v.object({
 export const Route = createFileRoute('/maintainers')({
   component: RouteComponent,
   validateSearch: searchSchema,
+  staticData: {
+    includeSearchInCanonical: true,
+  },
   head: () => ({
     meta: seo({
       title: 'Maintainers | TanStack',

diff --git a/src/routes/partners.index.tsx b/src/routes/partners.index.tsx
@@ -78,6 +78,9 @@ function getPartnerFilterAnalytics(search: PartnersSearch) {
 export const Route = createFileRoute('/partners/')({
   component: PartnersIndexPage,
   validateSearch: searchSchema,
+  staticData: {
+    includeSearchInCanonical: true,
+  },
   head: () => ({
     meta: seo({
       title: 'Partners',

diff --git a/src/routes/shop.collections.$handle.tsx b/src/routes/shop.collections.$handle.tsx
@@ -63,6 +63,9 @@ export const Route = createFileRoute('/shop/collections/$handle')({
     }
   },
   component: CollectionPage,
+  staticData: {
+    includeSearchInCanonical: true,
+  },
 })
 
 function CollectionPage() {

diff --git a/src/routes/shop.index.tsx b/src/routes/shop.index.tsx
@@ -47,6 +47,9 @@ export const Route = createFileRoute('/shop/')({
     return { page, sortId: sortOptionId(sortOption) }
   },
   component: ShopIndex,
+  staticData: {
+    includeSearchInCanonical: true,
+  },
 })
 
 function ShopIndex() {

diff --git a/src/routes/shop.search.tsx b/src/routes/shop.search.tsx
@@ -30,6 +30,9 @@ export const Route = createFileRoute('/shop/search')({
     return { query: q, totalCount: page.totalCount, page }
   },
   component: SearchPage,
+  staticData: {
+    includeSearchInCanonical: true,
+  },
 })
 
 function SearchPage() {

diff --git a/src/routes/stats/npm/$packages.tsx b/src/routes/stats/npm/$packages.tsx
@@ -76,6 +76,9 @@ export const Route = createFileRoute('/stats/npm/$packages')({
     }
   },
   component: RouteComponent,
+  staticData: {
+    includeSearchInCanonical: true,
+  },
 })
 
 function RouteComponent() {

diff --git a/src/routes/stats/npm/index.tsx b/src/routes/stats/npm/index.tsx
@@ -192,6 +192,7 @@ export const Route = createFileRoute('/stats/npm/')({
   },
   component: RouteComponent,
   staticData: {
+    includeSearchInCanonical: true,
     Title: () => {
       return (
         <Link

diff --git a/src/utils/seo.ts b/src/utils/seo.ts
@@ -35,14 +35,16 @@ export function shouldIndexPath(path: string) {
   return getCanonicalPath(path) !== null
 }
 
-export function canonicalUrl(path: string) {
+export function canonicalUrl(path: string, search?: string) {
   const origin = trimTrailingSlash(
     env.URL ||
       (import.meta.env.SSR ? env.SITE_URL : undefined) ||
       DEFAULT_SITE_URL,
   )
 
-  return `${origin}${normalizePath(path)}`
+  const normalizedSearch = search && search !== '?' ? search : ''
+
+  return `${origin}${normalizePath(path)}${normalizedSearch}`
 }
 
 type SeoOptions = {