fix: preserve search params in canonical URL on stateful routes (#864)

tannerlinsley · web-flow · commit 5194bcd3d401 · 2026-04-26T20:34:09.000-06:00
Adds an opt-in `staticData.includeSearchInCanonical` flag that threads
the current search string into the canonical link, og:url, and
twitter:url tags, so iOS Share preserves the user's configured view
on routes whose state lives in URL search params.

Applied to:
- /stats/npm/, /stats/npm/$packages, /$libraryId/$version/docs/npm-stats
- /builder
- /maintainers
- /partners
- /intent/registry
- /shop, /shop/search, /shop/collections/$handle
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 = {

Original file line number	Diff line number	Diff line change
`@@ -78,6 +78,7 @@ declare module '@tanstack/react-router' {`
`78`	`78`	`baseParent?: boolean`
`79`	`79`	`Title?: () => any`
`80`	`80`	`showNavbar?: boolean`
	`81`	`+ includeSearchInCanonical?: boolean`
`81`	`82`	`}`
`82`	`83`	`}`
`83`	`84`
Original file line number	Diff line number	Diff line change
`@@ -63,6 +63,9 @@ export const Route = createFileRoute('/shop/collections/$handle')({`
`63`	`63`	`}`
`64`	`64`	`},`
`65`	`65`	`component: CollectionPage,`
	`66`	`+ staticData: {`
	`67`	`+ includeSearchInCanonical: true,`
	`68`	`+ },`
`66`	`69`	`})`
`67`	`70`
`68`	`71`	`function CollectionPage() {`