feat(analytics): add PostHog tracking to Vercel onboarding

Introduce PostHog instrumentation in the VercelOnboardingModal to
capture user progress and actions during the onboarding flow.

Key changes:
- Import posthog and add a reusable trackOnboarding callback that
  attaches context (origin, step, organization_slug, project_slug).
- Start session recording and emit a "vercel onboarding started" event
  the first time the modal reaches project-selection while open.
- Track key milestones and user decisions:
  - "vercel onboarding project selected" when a project is chosen.
  - "vercel onboarding abandoned" when the user skips onboarding.
  - "vercel onboarding env mapping completed" with skipped flag or
    selected staging environment.
  - "vercel onboarding build settings completed".
  - "vercel onboarding completed" with github_connected flag.
- Ensure tracking callbacks are included in effect and callback deps
  to avoid stale closures and double-tracking.

Why:
- Provide visibility into onboarding funnel performance and user
  behaviors to improve onboarding UX and conversion.

Author: 0ski

apps/webapp/app/components/integrations/VercelOnboardingModal.tsx

@@ -47,6 +47,7 @@ import { type VercelOnboardingData } from "~/presenters/v3/VercelSettingsPresent
 import { vercelAppInstallPath, v3ProjectSettingsPath, githubAppInstallPath, vercelResourcePath } from "~/utils/pathBuilder";
 import type { loader } from "~/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.vercel";
 import { useEffect, useState, useCallback, useRef } from "react";
+import { usePostHogTracking } from "~/hooks/usePostHog";
 
 function safeRedirectUrl(url: string): string | null {
   try {
@@ -114,6 +115,7 @@ export function VercelOnboardingModal({
   nextUrl?: string;
   onDataReload?: (vercelStagingEnvironment?: string) => void;
 }) {
+  const { capture, startSessionRecording } = usePostHogTracking();
   const navigation = useNavigation();
   const fetcher = useTypedFetcher<typeof loader>();
   const envMappingFetcher = useFetcher();
@@ -172,6 +174,31 @@ export function VercelOnboardingModal({
     prevIsOpenRef.current = isOpen;
   }, [isOpen, state, computeInitialState]);
 
+  const trackOnboarding = useCallback(
+    (eventName: string, extraProperties?: Record<string, unknown>) => {
+      capture(eventName, {
+        origin: fromMarketplaceContext ? "marketplace" : "dashboard",
+        step: state,
+        organization_slug: organizationSlug,
+        project_slug: projectSlug,
+        ...extraProperties,
+      });
+    },
+    [capture, fromMarketplaceContext, state, organizationSlug, projectSlug]
+  );
+
+  const hasTrackedStartRef = useRef(false);
+  useEffect(() => {
+    if (isOpen && state === "project-selection" && !hasTrackedStartRef.current) {
+      hasTrackedStartRef.current = true;
+      startSessionRecording();
+      trackOnboarding("vercel onboarding started");
+    }
+    if (!isOpen) {
+      hasTrackedStartRef.current = false;
+    }
+  }, [isOpen, state, trackOnboarding, startSessionRecording]);
+
   const [selectedVercelProject, setSelectedVercelProject] = useState<{
     id: string;
     name: string;
@@ -337,14 +364,17 @@ export function VercelOnboardingModal({
 
   useEffect(() => {
     if (state === "project-selection" && fetcher.data && "success" in fetcher.data && fetcher.data.success && fetcher.state === "idle") {
+      trackOnboarding("vercel onboarding project selected", {
+        vercel_project_name: selectedVercelProject?.name,
+      });
       setState("loading-env-mapping");
       if (onDataReload) {
         onDataReload();
       }
     } else if (fetcher.data && "error" in fetcher.data && typeof fetcher.data.error === "string") {
       setProjectSelectionError(fetcher.data.error);
     }
-  }, [state, fetcher.data, fetcher.state, onDataReload]);
+  }, [state, fetcher.data, fetcher.state, onDataReload, trackOnboarding, selectedVercelProject?.name]);
 
   // For marketplace origin, skip env-mapping step
   useEffect(() => {
@@ -437,6 +467,7 @@ export function VercelOnboardingModal({
   }, [selectedVercelProject, fetcher, actionUrl]);
 
   const handleSkipOnboarding = useCallback(() => {
+    trackOnboarding("vercel onboarding abandoned");
     onClose();
 
     if (fromMarketplaceContext) {
@@ -449,14 +480,23 @@ export function VercelOnboardingModal({
       method: "post",
       action: actionUrl,
     });
-  }, [actionUrl, fetcher, onClose, nextUrl, fromMarketplaceContext]);
+  }, [actionUrl, fetcher, onClose, nextUrl, fromMarketplaceContext, trackOnboarding]);
 
   const handleSkipEnvMapping = useCallback(() => {
+    trackOnboarding("vercel onboarding env mapping completed", {
+      skipped: true,
+      staging_environment: null,
+    });
     setVercelStagingEnvironment(null);
     setState("loading-env-vars");
-  }, []);
+  }, [trackOnboarding]);
 
   const handleUpdateEnvMapping = useCallback(() => {
+    trackOnboarding("vercel onboarding env mapping completed", {
+      skipped: false,
+      staging_environment: vercelStagingEnvironment?.displayName ?? null,
+    });
+
     if (!vercelStagingEnvironment) {
       setState("loading-env-vars");
       return;
@@ -471,9 +511,11 @@ export function VercelOnboardingModal({
       action: actionUrl,
     });
 
-  }, [vercelStagingEnvironment, envMappingFetcher, actionUrl]);
+  }, [vercelStagingEnvironment, envMappingFetcher, actionUrl, trackOnboarding]);
 
   const handleBuildSettingsNext = useCallback(() => {
+    trackOnboarding("vercel onboarding build settings completed");
+
     if (nextUrl && fromMarketplaceContext && isGitHubConnectedForOnboarding) {
       setIsRedirecting(true);
     }
@@ -501,7 +543,7 @@ export function VercelOnboardingModal({
     if (!isGitHubConnectedForOnboarding) {
       setState("github-connection");
     }
-  }, [vercelStagingEnvironment, pullEnvVarsBeforeBuild, atomicBuilds, discoverEnvVars, syncEnvVarsMapping, nextUrl, fromMarketplaceContext, isGitHubConnectedForOnboarding, completeOnboardingFetcher, actionUrl]);
+  }, [vercelStagingEnvironment, pullEnvVarsBeforeBuild, atomicBuilds, discoverEnvVars, syncEnvVarsMapping, nextUrl, fromMarketplaceContext, isGitHubConnectedForOnboarding, completeOnboardingFetcher, actionUrl, trackOnboarding]);
 
   const handleFinishOnboarding = useCallback((e: React.FormEvent<HTMLFormElement>) => {
     e.preventDefault();
@@ -531,9 +573,12 @@ export function VercelOnboardingModal({
 
   useEffect(() => {
     if (state === "completed") {
+      trackOnboarding("vercel onboarding completed", {
+        github_connected: isGitHubConnectedForOnboarding,
+      });
       onClose();
     }
-  }, [state, onClose]);
+  }, [state, onClose, trackOnboarding, isGitHubConnectedForOnboarding]);
 
   useEffect(() => {
     if (state === "installing") {
@@ -584,7 +629,14 @@ export function VercelOnboardingModal({
 
   if (isLoadingState) {
     return (
-      <Dialog open={isOpen} onOpenChange={(open) => !open && !fromMarketplaceContext && onClose()}>
+      <Dialog open={isOpen} onOpenChange={(open) => {
+        if (!open && !fromMarketplaceContext) {
+          if (state as string !== "completed") {
+            trackOnboarding("vercel onboarding abandoned");
+          }
+          onClose();
+        }
+      }}>
         <DialogContent className="max-w-lg">
           <DialogHeader>
             <div className="flex items-center gap-2">
@@ -607,7 +659,14 @@ export function VercelOnboardingModal({
   const showGitHubConnection = state === "github-connection";
 
   return (
-    <Dialog open={isOpen} onOpenChange={(open) => !open && !fromMarketplaceContext && onClose()}>
+    <Dialog open={isOpen} onOpenChange={(open) => {
+      if (!open && !fromMarketplaceContext) {
+        if (state !== "completed") {
+          trackOnboarding("vercel onboarding abandoned");
+        }
+        onClose();
+      }
+    }}>
       <DialogContent className="max-w-lg">
         <DialogHeader>
           <div className="flex items-center gap-2">
@@ -902,6 +961,10 @@ export function VercelOnboardingModal({
                   <Button
                     variant="primary/medium"
                     onClick={() => {
+                      trackOnboarding("vercel onboarding env vars configured", {
+                        env_vars_enabled: enabledEnvVars.length,
+                        env_vars_total: syncableEnvVars.length,
+                      });
                       if (fromMarketplaceContext) {
                         handleBuildSettingsNext();
                       } else {

apps/webapp/app/hooks/usePostHog.ts

@@ -1,6 +1,6 @@
 import { useLocation } from "@remix-run/react";
 import posthog from "posthog-js";
-import { useEffect, useRef } from "react";
+import { useCallback, useEffect, useRef } from "react";
 import { useOrganizationChanged } from "./useOrganizations";
 import { useOptionalUser, useUserChanged } from "./useUser";
 import { useProjectChanged } from "./useProject";
@@ -68,3 +68,18 @@ export const usePostHog = (apiKey?: string, logging = false, debug = false): voi
     posthog.capture("$pageview");
   }, [location, logging]);
 };
+
+export function usePostHogTracking() {
+  const capture = useCallback(
+    (eventName: string, properties?: Record<string, unknown>) => {
+      posthog.capture(eventName, properties);
+    },
+    []
+  );
+
+  const startSessionRecording = useCallback(() => {
+    posthog.startSessionRecording();
+  }, []);
+
+  return { capture, startSessionRecording };
+}