From 309f4b26121d8bf3e6eefa1af9ee099df10538ba Mon Sep 17 00:00:00 2001
From: Chris Chinchilla <chris.ward@supabase.io>
Date: Wed, 17 Jun 2026 16:56:53 +0200
Subject: [PATCH] docs: Track 404 recommendation clicked (#46990)

## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.

YES


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added analytics telemetry for documentation 404 recommendation clicks,
recording the clicked destination and the originating page.

* **Improvements**
* Enhanced the ButtonCard component to optionally handle click actions
via an `onClick` callback and forward it to the underlying link element.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 apps/docs/components/ButtonCard.tsx           |  5 ++++-
 .../recommendations/NotFound.client.tsx       | 16 ++++++++++----
 packages/common/telemetry-constants.ts        | 21 +++++++++++++++++++
 3 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/apps/docs/components/ButtonCard.tsx b/apps/docs/components/ButtonCard.tsx
index f7df15298f3..a8e679f9b2c 100644
--- a/apps/docs/components/ButtonCard.tsx
+++ b/apps/docs/components/ButtonCard.tsx
@@ -1,6 +1,6 @@
-import React, { FC } from 'react'
 import Image from 'next/legacy/image'
 import Link from 'next/link'
+import React, { FC } from 'react'
 import { cn } from 'ui'
 
 interface Props {
@@ -11,6 +11,7 @@ interface Props {
   children?: any
   layout?: 'vertical' | 'horizontal'
   className?: string
+  onClick?: () => void
 }
 
 const ButtonCard: FC<Props> = ({
@@ -21,10 +22,12 @@ const ButtonCard: FC<Props> = ({
   to,
   layout = 'vertical',
   className,
+  onClick,
 }) => {
   return (
     <Link
       href={to}
+      onClick={onClick}
       className={cn(
         'h-full block shadow-none bg-surface-100 rounded-sm transition',
         'border border-transparent hover:border-overlay',
diff --git a/apps/docs/features/recommendations/NotFound.client.tsx b/apps/docs/features/recommendations/NotFound.client.tsx
index b418fb2128b..15c64133316 100644
--- a/apps/docs/features/recommendations/NotFound.client.tsx
+++ b/apps/docs/features/recommendations/NotFound.client.tsx
@@ -1,15 +1,14 @@
 'use client'
 
+import ButtonCard from '~/components/ButtonCard'
+import { useSendTelemetryEvent } from '~/lib/telemetry'
+import { useDocsSearch, type DocsSearchResult } from 'common'
 import { usePathname } from 'next/navigation'
 import { useEffect } from 'react'
-
-import { useDocsSearch, type DocsSearchResult } from 'common'
 import { Button, cn } from 'ui'
 import { useSetCommandMenuOpen } from 'ui-patterns/CommandMenu'
 import { GenericSkeletonLoader } from 'ui-patterns/ShimmeringLoader'
 
-import ButtonCard from '~/components/ButtonCard'
-
 function SearchButton() {
   const setCommandMenuOpen = useSetCommandMenuOpen()
 
@@ -65,6 +64,9 @@ function RecommendationsList({
 }: {
   recommendations: Array<Omit<DocsSearchResult, 'sections'>>
 }) {
+  const pathname = usePathname()
+  const sendTelemetryEvent = useSendTelemetryEvent()
+
   return (
     <ul className={cn('not-prose', 'grid grid-cols-[repeat(auto-fit,minmax(300px,1fr))] gap-4')}>
       {recommendations
@@ -76,6 +78,12 @@ function RecommendationsList({
             to={path}
             title={title}
             description={subtitle || description || undefined}
+            onClick={() =>
+              sendTelemetryEvent({
+                action: 'docs_404_recommendation_clicked',
+                properties: { destinationPath: path, sourcePath: pathname ?? '' },
+              })
+            }
           />
         ))}
     </ul>
diff --git a/packages/common/telemetry-constants.ts b/packages/common/telemetry-constants.ts
index 9d73133da48..f5a8280f32d 100644
--- a/packages/common/telemetry-constants.ts
+++ b/packages/common/telemetry-constants.ts
@@ -838,6 +838,26 @@ export interface AskAIEvent {
   }
 }
 
+/**
+ * User clicked a recommended page card shown on a docs "not found" page.
+ *
+ * @group Events
+ * @source docs
+ */
+export interface DocsRecommendation404ClickedEvent {
+  action: 'docs_404_recommendation_clicked'
+  properties: {
+    /**
+     * The path of the recommended page that was clicked.
+     */
+    destinationPath: string
+    /**
+     * The path of the "not found" page where the recommendation was shown.
+     */
+    sourcePath: string
+  }
+}
+
 /**
  * User clicked the framework quickstart card on the homepage, leading to the specific framework documentation.
  *
@@ -3460,6 +3480,7 @@ export type TelemetryEvent =
   | DocsFeedbackClickedEvent
   | CopyAsMarkdownEvent
   | AskAIEvent
+  | DocsRecommendation404ClickedEvent
   | HomepageFrameworkQuickstartClickedEvent
   | HomepageProductCardClickedEvent
   | WwwPricingPlanCtaClickedEvent