adding-analytics

name	adding-analytics
description	Add PostHog analytics to a web application, including event tracking, page views, feature flags, and session replay.

Add Analytics (PostHog)

Use this skill when the user asks to add analytics, event tracking, page views, feature flags, or session replay to a web application.

Steps

1. Detect the framework — check for next.config.*, vite.config.*, package.json scripts, or index.html to determine if this is Next.js, React (Vite/CRA), Vue, Svelte, or plain HTML.

2. Install the SDK

   • Next.js / React: npm install posthog-js
   • Next.js (server-side): npm install posthog-js posthog-node
   • Python: pip install posthog
   • Node.js backend: npm install posthog-node

3. Create a provider / init module

   • For Next.js App Router, create app/providers.tsx:

     "use client";
     import posthog from "posthog-js";
     import { PostHogProvider as PHProvider } from "posthog-js/react";
     import { useEffect } from "react";
     
     export function PostHogProvider({ children }: { children: React.ReactNode }) {
       useEffect(() => {
         posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
           api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST ?? "https://us.i.posthog.com",
           capture_pageview: false, // we capture manually for SPAs
         });
       }, []);
       return <PHProvider client={posthog}>{children}</PHProvider>;
     }
     

   • Wrap {children} in the root layout with <PostHogProvider>.

   • For Pages Router, init in _app.tsx inside a useEffect.

4. Add page-view tracking — for SPAs, create a component that calls posthog.capture('$pageview') on route change using the framework's router events.

5. Add .env variables — prompt the user for their PostHog project API key and host:

   NEXT_PUBLIC_POSTHOG_KEY=phc_...
   NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
   

   Add these keys to .env.example as well.

6. Add custom events — if the user specifies events to track (e.g. sign-up, purchase), add posthog.capture("event_name", { ...properties }) calls in the relevant handlers.

7. Feature flags (optional) — if requested, show how to use posthog.isFeatureEnabled("flag-name") or the useFeatureFlagEnabled hook.

8. Session replay (optional) — enable by adding session_recording: { maskAllInputs: false } to the init config if requested.

Notes

• Never hardcode API keys — always use environment variables.
• Add posthog-js to the Content Security Policy if the project has one.
• For monorepos, install in the package that renders the UI, not the root.