feat: add PostHog tracking for docs feedback (#101)

- Add posthog-node for server-side event capture
- Create combined feedback adapter (Slack + PostHog)
- Track docs_feedback_submitted, docs_feedback_helpful, docs_feedback_not_helpful events
- Include page URL, category, and message in event properties
- Enable session recording with password masking

Amp-Thread-ID: https://ampcode.com/threads/T-019c4d62-38c2-7005-bbd3-3ad64e139c61

Co-authored-by: Amp <amp@ampcode.com>

Author: gakonst

package.json

@@ -25,6 +25,7 @@
     "monaco-editor": "^0.55.1",
     "ox": "^0.11.3",
     "posthog-js": "^1.333.0",
+    "posthog-node": "^5.24.15",
     "prool": "^0.2.2",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",

pnpm-lock.yaml

@@ -16,6 +16,12 @@ function PostHogInitializer() {
       defaults: '2025-11-30',
       capture_exceptions: true,
       debug: import.meta.env.MODE === 'development',
+      session_recording: {
+        maskAllInputs: false,
+        maskInputOptions: {
+          password: true,
+        },
+      },
     })
 
     posthog.register({ site: 'docs' })

src/components/PostHogSetup.tsx

@@ -0,0 +1,70 @@
+import { PostHog } from 'posthog-node'
+import { Feedback } from 'vocs/config'
+import { POSTHOG_EVENTS, POSTHOG_PROPERTIES } from './posthog'
+
+type FeedbackData = {
+  helpful: boolean
+  category?: string | undefined
+  message?: string | undefined
+  pageUrl: string
+  timestamp: string
+}
+
+export function createFeedbackAdapter() {
+  const slackAdapter = Feedback.slack()
+
+  const posthogKey = process.env.VITE_POSTHOG_KEY
+  const posthogHost = process.env.VITE_POSTHOG_HOST || 'https://us.i.posthog.com'
+
+  const posthog = posthogKey ? new PostHog(posthogKey, { host: posthogHost }) : null
+
+  return Feedback.from({
+    type: 'slack+posthog',
+    async submit(data: FeedbackData) {
+      const slackPromise = slackAdapter.submit(data)
+
+      const posthogPromise = (async () => {
+        if (!posthog) return
+
+        let pagePath: string | undefined
+        try {
+          pagePath = new URL(data.pageUrl).pathname
+        } catch {
+          pagePath = undefined
+        }
+
+        const distinctId = `docs_feedback_${Date.now()}_${Math.random().toString(36).slice(2)}`
+        const ts = data.timestamp ? new Date(data.timestamp) : undefined
+
+        const commonProperties = {
+          [POSTHOG_PROPERTIES.FEEDBACK_HELPFUL]: data.helpful,
+          [POSTHOG_PROPERTIES.FEEDBACK_CATEGORY]: data.category,
+          [POSTHOG_PROPERTIES.FEEDBACK_MESSAGE]: data.message,
+          [POSTHOG_PROPERTIES.FEEDBACK_PAGE_URL]: data.pageUrl,
+          [POSTHOG_PROPERTIES.PAGE_PATH]: pagePath,
+          [POSTHOG_PROPERTIES.SITE]: 'docs',
+        }
+
+        posthog.capture({
+          distinctId,
+          event: POSTHOG_EVENTS.FEEDBACK_SUBMITTED,
+          properties: commonProperties,
+          timestamp: ts,
+        })
+
+        posthog.capture({
+          distinctId,
+          event: data.helpful
+            ? POSTHOG_EVENTS.FEEDBACK_HELPFUL
+            : POSTHOG_EVENTS.FEEDBACK_NOT_HELPFUL,
+          properties: commonProperties,
+          timestamp: ts,
+        })
+
+        await posthog.flush()
+      })().catch(() => {})
+
+      await Promise.allSettled([slackPromise, posthogPromise])
+    },
+  })
+}

src/lib/feedback-adapter.ts

@@ -35,6 +35,11 @@ export const POSTHOG_EVENTS = {
   // Code interactions
   CODE_EXAMPLE_VIEW: 'docs_code_example_view',
   CODE_EXAMPLE_COPY: 'docs_code_example_copy',
+
+  // Feedback
+  FEEDBACK_SUBMITTED: 'docs_feedback_submitted',
+  FEEDBACK_HELPFUL: 'docs_feedback_helpful',
+  FEEDBACK_NOT_HELPFUL: 'docs_feedback_not_helpful',
 } as const
 
 /**
@@ -68,6 +73,12 @@ export const POSTHOG_PROPERTIES = {
   SEARCH_QUERY: 'search_query',
   SEARCH_RESULT_TITLE: 'search_result_title',
   SEARCH_RESULT_URL: 'search_result_url',
+
+  // Feedback properties
+  FEEDBACK_HELPFUL: 'feedback_helpful',
+  FEEDBACK_CATEGORY: 'feedback_category',
+  FEEDBACK_MESSAGE: 'feedback_message',
+  FEEDBACK_PAGE_URL: 'feedback_page_url',
 } as const
 
 /**

src/lib/posthog.ts

@@ -1,4 +1,5 @@
-import { Changelog, defineConfig, Feedback, McpSource } from 'vocs/config'
+import { Changelog, defineConfig, McpSource } from 'vocs/config'
+import { createFeedbackAdapter } from './src/lib/feedback-adapter'
 
 const baseUrl = (() => {
   if (URL.canParse(process.env.VITE_BASE_URL)) return process.env.VITE_BASE_URL
@@ -22,7 +23,7 @@ export default defineConfig({
   title: 'Tempo',
   titleTemplate: '%s ⋅ Tempo',
   description: 'Documentation for the Tempo network and protocol specifications',
-  feedback: Feedback.slack(),
+  feedback: createFeedbackAdapter(),
   mcp: {
     enabled: true,
     sources: [