chore: add basic default opt out instrumentation

Author: haritabh-z01

apps/admin/.env.example

@@ -38,3 +38,11 @@ RESEND_API_KEY=""
 # REFERRAL_PROGRAM_CLIENT_SECRET=""
 # NEXT_PUBLIC_REFREF_PROJECT_ID=""
 # NEXT_PUBLIC_REFREF_PROGRAM_ID=""
+
+# PostHog Analytics (OPTIONAL)
+# Required only if you want to enable analytics and feature flags
+# Get your project key from: https://posthog.com/
+# Leave NEXT_PUBLIC_POSTHOG_KEY empty to disable PostHog entirely (no console errors)
+# Set NEXT_PUBLIC_POSTHOG_ENABLED to false to opt out of tracking while keeping PostHog initialized
+NEXT_PUBLIC_POSTHOG_KEY=""
+NEXT_PUBLIC_POSTHOG_ENABLED="true"

apps/admin/.gitignore

@@ -0,0 +1 @@
+.env

apps/admin/instrumentation-client.ts

@@ -0,0 +1,22 @@
+import posthog from "posthog-js";
+import { env } from "./src/env";
+
+// Only initialize PostHog if key is present and enabled
+if (env.NEXT_PUBLIC_POSTHOG_KEY) {
+  if (env.NEXT_PUBLIC_POSTHOG_ENABLED) {
+    posthog.init(env.NEXT_PUBLIC_POSTHOG_KEY, {
+      api_host: "/ingest",
+      ui_host: "https://us.posthog.com",
+      defaults: "2025-05-24",
+      capture_exceptions: true, // This enables capturing exceptions using Error Tracking
+      debug: process.env.NODE_ENV === "development",
+      loaded: (ph) => {
+        if (!env.NEXT_PUBLIC_POSTHOG_ENABLED) {
+          ph.opt_out_capturing();
+        }
+      },
+    });
+  }
+}
+
+export { posthog };

apps/admin/next.config.ts

@@ -15,6 +15,19 @@ const config: NextConfig = {
       },
     ];
   },
+  async rewrites() {
+    return [
+      {
+        source: "/ingest/static/:path*",
+        destination: "https://us-assets.i.posthog.com/static/:path*",
+      },
+      {
+        source: "/ingest/:path*",
+        destination: "https://us.i.posthog.com/:path*",
+      },
+    ];
+  },
+  skipTrailingSlashRedirect: true,
   transpilePackages: ["@refref/ui"],
   typescript: {
     ignoreBuildErrors: false,

apps/admin/package.json

@@ -82,6 +82,8 @@
     "nuqs": "2.4.3",
     "plugins": "link:better-auth/client/plugins",
     "postgres": "^3.4.5",
+    "posthog-js": "^1.281.0",
+    "posthog-node": "^5.10.4",
     "react": "^19.0.0",
     "react-aria-components": "^1.8.0",
     "react-day-picker": "8.10.1",

apps/admin/src/app/layout.tsx

@@ -7,6 +7,7 @@ import { NuqsAdapter } from "nuqs/adapters/next/app";
 
 import { TRPCReactProvider } from "@/trpc/react";
 import { AuthUIProvider } from "@/components/providers/auth-ui-provider";
+import { PostHogProvider } from "@/components/providers/posthog-provider";
 
 export const metadata: Metadata = {
   title: "RefRef - Referral Management Platform",
@@ -59,7 +60,9 @@ export default function RootLayout({
         >
           <TRPCReactProvider>
             <AuthUIProvider>
-              <NuqsAdapter>{children}</NuqsAdapter>
+              <PostHogProvider>
+                <NuqsAdapter>{children}</NuqsAdapter>
+              </PostHogProvider>
             </AuthUIProvider>
           </TRPCReactProvider>
         </ThemeProvider>

apps/admin/src/components/providers/posthog-provider.tsx

@@ -0,0 +1,42 @@
+"use client";
+
+import { PostHogProvider as PHProvider } from "posthog-js/react";
+import posthog from "posthog-js";
+import { useSession } from "@/lib/auth-client";
+import { useEffect } from "react";
+
+function PostHogIdentifier() {
+  const { data: session, isPending } = useSession();
+
+  useEffect(() => {
+    // Skip if session is still loading
+    if (isPending) {
+      return;
+    }
+
+    // Identify user when authenticated
+    if (session?.user) {
+      posthog.identify(session.user.id, {
+        email: session.user.email,
+        name: session.user.name,
+        ...(session.session?.activeOrganizationId && {
+          activeOrganizationId: session.session.activeOrganizationId,
+        }),
+      });
+    } else {
+      // Reset PostHog when user logs out
+      posthog.reset();
+    }
+  }, [session, isPending]);
+
+  return null;
+}
+
+export function PostHogProvider({ children }: { children: React.ReactNode }) {
+  return (
+    <PHProvider client={posthog}>
+      <PostHogIdentifier />
+      {children}
+    </PHProvider>
+  );
+}

apps/admin/src/env.ts

@@ -18,7 +18,9 @@ export const env = createEnv({
     GOOGLE_CLIENT_SECRET: z.string().min(1).default("google_client_secret"),
     REFERRAL_PROGRAM_CLIENT_ID: z.string().optional(),
     REFERRAL_PROGRAM_CLIENT_SECRET: z.string().optional(),
-    NOTIFICATIONS_EMAIL_FROM: z.string().default("RefRef <notifications@mail.refref.ai>")
+    NOTIFICATIONS_EMAIL_FROM: z
+      .string()
+      .default("RefRef <notifications@mail.refref.ai>"),
   },
 
   /**
@@ -51,6 +53,11 @@ export const env = createEnv({
               .filter(Boolean)
           : [],
       ),
+    NEXT_PUBLIC_POSTHOG_KEY: z.string().optional(),
+    NEXT_PUBLIC_POSTHOG_ENABLED: z
+      .enum(["true", "false"])
+      .default("false")
+      .transform((val) => val === "true"),
   },
 
   /**
@@ -77,6 +84,8 @@ export const env = createEnv({
     NEXT_PUBLIC_ENABLED_SOCIAL_AUTH:
       process.env.NEXT_PUBLIC_ENABLED_SOCIAL_AUTH,
     NOTIFICATIONS_EMAIL_FROM: process.env.NOTIFICATIONS_EMAIL_FROM,
+    NEXT_PUBLIC_POSTHOG_KEY: process.env.NEXT_PUBLIC_POSTHOG_KEY,
+    NEXT_PUBLIC_POSTHOG_ENABLED: process.env.NEXT_PUBLIC_POSTHOG_ENABLED,
   },
   /**
    * Run `build` or `dev` with `SKIP_ENV_VALIDATION` to skip env validation. This is especially