Claude Skill

api-analytics-setup-posthog

PostHog analytics and feature flags setup

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download agents-inc-skills-dist_plugins_api-analytics-setup-posthog_skills_api-analytics-setup-posthog-707467a.zip · 7 KB

Install

skills CLI npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/api-analytics-setup-posthog/skills/api-analytics-setup-posthog
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart
Git git clone https://github.com/agents-inc/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole agents-inc/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

PostHog Analytics & Feature Flags Setup

Quick Guide: One-time setup for PostHog analytics and feature flags. Covers posthog-js client provider, posthog-node server client, and environment variables. PostHog handles both analytics AND feature flags with a generous free tier (1M events + 1M flag requests/month).


<critical_requirements>

CRITICAL: Before Using This Skill

(You MUST initialize posthog-js only in a client/browser context - it requires browser APIs like window and localStorage)

(You MUST call posthog.shutdown(), posthog.flush(), or use captureImmediate() after server-side event capture to prevent lost events)

(You MUST use defaults: '2026-01-30' for automatic SPA page tracking and latest recommended behaviors)

</critical_requirements>


Auto-detection: PostHog setup, posthog-js, posthog-node, PostHogProvider, analytics setup, feature flags setup, event tracking setup, posthog.init

When to use:

  • Initial PostHog setup in a project
  • Configuring PostHogProvider for client-side analytics
  • Setting up posthog-node for server-side/API route event capture
  • Configuring environment variables for PostHog

When NOT to use:

  • Event tracking patterns after setup (use analytics event tracking skill)
  • Feature flag usage patterns (use feature flags skill)
  • Complex multi-environment setups with separate staging/production projects

Key patterns covered:

  • Client-side setup with PostHogProvider or framework initialization hook
  • Server-side setup with posthog-node
  • Environment variables (client vs server prefix)
  • User identification and reset flows
  • Serverless flush patterns (captureImmediate vs flush)

Detailed Resources:




<red_flags>

RED FLAGS

  • Initializing posthog-js on the server (requires browser APIs - will crash)
  • No flush() or captureImmediate() after server-side capture in serverless environments (events silently lost)
  • Client-side env vars not exposed to the browser bundle (check your framework's prefix convention)
  • Hardcoding API keys in source code instead of environment variables
  • Missing posthog.reset() on sign out (user identity bleeds to next session)
  • Not using defaults date option (manual pageview tracking required, misses recommended behaviors)
  • Not calling posthog.identify() after authentication (anonymous and authenticated sessions remain unlinked)
  • No person_profiles: 'identified_only' option (unnecessary anonymous profiles created, higher costs)
  • Not wrapping app with PostHogProvider when using hooks (hooks return null)
  • Forgetting to add environment variables to deployment platform (events fail silently)
  • Using different PostHog projects for dev/prod without realizing (separate data)

Gotchas & Edge Cases:

  • posthog-js must be initialized after window is available (hence useEffect or a client-side initialization hook)
  • Server-side SDK does NOT auto-flush like the client - you must explicitly call flush(), shutdown(), or use captureImmediate()
  • captureImmediate() is simpler for serverless but sends one HTTP request per event (no batching)
  • Free tier resets monthly (1M events then stops capturing until next month)
  • person_profiles: 'identified_only' reduces costs but means no anonymous user profiles are created
  • When using auto-initialization hooks, config values remain fixed for the session - bootstrapping only works if flags are evaluated on the server before render

</red_flags>


<critical_reminders>

CRITICAL REMINDERS

(You MUST initialize posthog-js only in a client/browser context - it requires browser APIs like window and localStorage)

(You MUST call posthog.shutdown(), posthog.flush(), or use captureImmediate() after server-side event capture to prevent lost events)

(You MUST use defaults: '2026-01-30' for automatic SPA page tracking and latest recommended behaviors)

Failure to follow these rules will cause lost analytics events, broken tracking, or security vulnerabilities.

</critical_reminders>


Sources

Files (skills)
  • examples
    • core.md 5.9 KB
      Loading…
    • server.md 3.7 KB
      Loading…
  • reference.md 1.4 KB
    Loading…
  • SKILL.md 7.3 KB
    ---
    name: api-analytics-setup-posthog
    description: PostHog analytics and feature flags setup
    ---
    
    # PostHog Analytics & Feature Flags Setup
    
    > **Quick Guide:** One-time setup for PostHog analytics and feature flags. Covers `posthog-js` client provider, `posthog-node` server client, and environment variables. PostHog handles both analytics AND feature flags with a generous free tier (1M events + 1M flag requests/month).
    
    ---
    
    <critical_requirements>
    
    ## CRITICAL: Before Using This Skill
    
    **(You MUST initialize posthog-js only in a client/browser context - it requires browser APIs like window and localStorage)**
    
    **(You MUST call `posthog.shutdown()`, `posthog.flush()`, or use `captureImmediate()` after server-side event capture to prevent lost events)**
    
    **(You MUST use `defaults: '2026-01-30'` for automatic SPA page tracking and latest recommended behaviors)**
    
    </critical_requirements>
    
    ---
    
    **Auto-detection:** PostHog setup, posthog-js, posthog-node, PostHogProvider, analytics setup, feature flags setup, event tracking setup, posthog.init
    
    **When to use:**
    
    - Initial PostHog setup in a project
    - Configuring PostHogProvider for client-side analytics
    - Setting up posthog-node for server-side/API route event capture
    - Configuring environment variables for PostHog
    
    **When NOT to use:**
    
    - Event tracking patterns after setup (use analytics event tracking skill)
    - Feature flag usage patterns (use feature flags skill)
    - Complex multi-environment setups with separate staging/production projects
    
    **Key patterns covered:**
    
    - Client-side setup with PostHogProvider or framework initialization hook
    - Server-side setup with posthog-node
    - Environment variables (client vs server prefix)
    - User identification and reset flows
    - Serverless flush patterns (captureImmediate vs flush)
    
    **Detailed Resources:**
    
    - [examples/core.md](examples/core.md) - Provider setup, layout integration, user identification, env vars
    - [examples/server.md](examples/server.md) - Server client singleton, API routes, serverless patterns
    - [reference.md](reference.md) - Decision frameworks
    
    ---
    
    <philosophy>
    
    ## Philosophy
    
    PostHog is a **product analytics + feature flags platform** that consolidates multiple tools into one. It's open-source, can be self-hosted, and has a generous free tier. For solo developers and small teams, PostHog eliminates the need for separate analytics and feature flag services.
    
    **Core principles:**
    
    1. **One platform for analytics + feature flags** - Reduces tool sprawl and cost
    2. **Usage-based pricing** - Pay for what you use, not per-project
    3. **Autocapture by default** - Automatic event tracking reduces manual instrumentation
    4. **Server and client SDKs** - Full coverage for SSR and client-side apps
    
    **When to use PostHog:**
    
    - Need both analytics and feature flags in one platform
    - Want generous free tier (1M events + 1M flag requests/month)
    - Prefer open-source with self-host option
    - Building product analytics (funnels, retention, sessions)
    
    **When NOT to use PostHog:**
    
    - Need advanced A/B testing with statistical rigor
    - Require real-time event streaming
    - Already have established analytics + flag tools
    
    </philosophy>
    
    ---
    
    <patterns>
    
    ## Core Patterns
    
    ### Pattern 1: PostHog Project Structure
    
    Use a single PostHog organization for your apps. One org pools billing. Use separate projects per app, or one project with custom properties to filter.
    
    ```
    PostHog Organization: "Your Company"
    ├── Project: "Main App" (or separate per app)
    │   ├── API Key: phc_xxx
    │   └── Host: https://us.i.posthog.com (or eu.i.posthog.com)
    ```
    
    **Why good:** Single org pools billing across all projects, usage-based pricing, 6 projects included on paid tier
    
    ---
    
    ### Pattern 2: Client-Side Setup
    
    Install `posthog-js` and configure a provider or use your framework's client-side initialization hook.
    
    Key config options: `defaults: "2026-01-30"` enables recommended behaviors, `person_profiles: "identified_only"` reduces costs.
    
    See [examples/core.md](examples/core.md) for full implementation of both approaches.
    
    **Why good:** `defaults` date enables automatic SPA page/leave tracking, `person_profiles: "identified_only"` reduces event costs, debug mode in development aids troubleshooting
    
    ---
    
    ### Pattern 3: Server-Side Setup with posthog-node
    
    Install `posthog-node` and create a singleton for server-side event capture.
    
    **Serverless flush options:**
    
    - `captureImmediate()` - simplest, awaits HTTP request directly (one request per event)
    - `capture()` + `await flush()` - batched, requires explicit flush before response returns
    
    See [examples/server.md](examples/server.md) for singleton setup, API route usage, and the flush anti-pattern.
    
    **Why good:** Singleton prevents multiple client instances, flushInterval/flushAt configure batching, captureImmediate simplifies serverless usage
    
    </patterns>
    
    ---
    
    <red_flags>
    
    ## RED FLAGS
    
    - Initializing posthog-js on the server (requires browser APIs - will crash)
    - No `flush()` or `captureImmediate()` after server-side capture in serverless environments (events silently lost)
    - Client-side env vars not exposed to the browser bundle (check your framework's prefix convention)
    - Hardcoding API keys in source code instead of environment variables
    - Missing `posthog.reset()` on sign out (user identity bleeds to next session)
    - Not using `defaults` date option (manual pageview tracking required, misses recommended behaviors)
    - Not calling `posthog.identify()` after authentication (anonymous and authenticated sessions remain unlinked)
    - No `person_profiles: 'identified_only'` option (unnecessary anonymous profiles created, higher costs)
    - Not wrapping app with PostHogProvider when using hooks (hooks return null)
    - Forgetting to add environment variables to deployment platform (events fail silently)
    - Using different PostHog projects for dev/prod without realizing (separate data)
    
    **Gotchas & Edge Cases:**
    
    - `posthog-js` must be initialized after `window` is available (hence useEffect or a client-side initialization hook)
    - Server-side SDK does NOT auto-flush like the client - you must explicitly call `flush()`, `shutdown()`, or use `captureImmediate()`
    - `captureImmediate()` is simpler for serverless but sends one HTTP request per event (no batching)
    - Free tier resets monthly (1M events then stops capturing until next month)
    - `person_profiles: 'identified_only'` reduces costs but means no anonymous user profiles are created
    - When using auto-initialization hooks, config values remain fixed for the session - bootstrapping only works if flags are evaluated on the server before render
    
    </red_flags>
    
    ---
    
    <critical_reminders>
    
    ## CRITICAL REMINDERS
    
    **(You MUST initialize posthog-js only in a client/browser context - it requires browser APIs like window and localStorage)**
    
    **(You MUST call `posthog.shutdown()`, `posthog.flush()`, or use `captureImmediate()` after server-side event capture to prevent lost events)**
    
    **(You MUST use `defaults: '2026-01-30'` for automatic SPA page tracking and latest recommended behaviors)**
    
    **Failure to follow these rules will cause lost analytics events, broken tracking, or security vulnerabilities.**
    
    </critical_reminders>
    
    ---
    
    ## Sources
    
    - [PostHog JavaScript SDK](https://posthog.com/docs/libraries/js)
    - [PostHog JavaScript Configuration](https://posthog.com/docs/libraries/js/config)
    - [PostHog Node.js SDK](https://posthog.com/docs/libraries/node)
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.