Skip to content
Skills Library
Programming · Tool integration

posthog-install-auth

/posthog-install-auth

Install an official PostHog SDK and configure the correct project token, regional host, and server-only credentials. Use when bootstrapping or repairing SDK authentication. Trigger with "install PostHog", "configure PostHog", or "PostHog API key".

Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
13
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Install an official PostHog SDK and configure the correct project token, regional host, and server-only credentials. Use when bootstrapping or repairing SDK authentication. Trigger with "install PostHog", "configure PostHog", or "PostHog API key".

Triggers from the description

install PostHogconfigure PostHogPostHog API key

Arguments

/posthog-install-auth [project-path] [sdk] [region]
Original author description

Install an official PostHog SDK and configure the correct project token, regional host, and server-only credentials. Use when bootstrapping or repairing SDK authentication. Trigger with "install PostHog", "configure PostHog", or "PostHog API key".

How it works

  1. Overview
  2. Prerequisites
  3. Instructions
  4. API Key Reference
  5. API Hosts
  6. Error Handling
  7. Output
  8. Examples
  9. Resources
  10. Next Steps
Original SKILL.md headings · 182 lines, 781 words
SKILL.md preview
---
name: posthog-install-auth
description: |
  Install an official PostHog SDK and configure the correct project token, regional host, and server-only credentials. Use when bootstrapping or repairing SDK authentication. Trigger with "install PostHog", "configure PostHog", or "PostHog API key".
argument-hint: "[project-path] [sdk] [region]"
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(pip:*), Grep
version: 1.14.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- posthog
- api
- authentication
compatibility: Designed for Claude Code
---
# PostHog Install & Auth

## Overview

Install PostHog SDKs and configure authentication. PostHog uses two key types: **Project API Key** (`phc_...`) for event capture (public, safe for frontend) and **Personal API Key** (`phx_...`) for private API endpoints (never expose to clients).

## Prerequisites

- Node.js 20+ or Python 3.10+
- PostHog account at [app.posthog.com](https://app.posthog.com)
- Project API key from Project Settings > Project API Key
- Personal API key from Settings > Personal API Keys (for server-side admin)

## Instructions

### Tool discipline

Use `Read` to inspect the relevant configuration and implementation before proposing changes. Use `Grep` to locate initialization, capture, flag, and credential boundaries. Use `Write` only for a new, explicitly requested artifact inside the target project. Use `Edit` for minimal changes to existing project files after the evidence pass.

### Step 1: Install the SDK

```bash
set -euo pipefail
# Browser SDK (posthog-js)
npm install posthog-js

# Node.js server SDK (posthog-node)
npm install posthog-node

# Python SDK
pip install posthog
```

### Step 2: Configure Environment Variables

```bash
# .env (add to .gitignore — never commit)
NEXT_PUBLIC_POSTHOG_KEY=phc_your_project_api_key    # Safe for frontend
POSTHOG_HOST=https://us.i.posthog.com               # US Cloud (or eu.i.posthog.com)
POSTHOG_PERSONAL_API_KEY=phx_your_personal_key      # Server-only, never expose
POSTHOG_FEATURE_FLAGS_SECURE_API_KEY=your_project_specific_secure_key # Server-side only
POSTHOG_PROJECT_ID=12345                             # From project URL
```

### Step 3: Initialize Browser SDK (posthog-js)

```typescript
// lib/posthog.ts
import posthog from 'posthog-js';

export function initPostHog() {
  if (typeof window === 'undefined') return;

  posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
    api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST || 'https://us.i.posthog.com',
    capture_pageview: true,        // Auto-capture $pageview
    capture_pageleave: true,       // Auto-capture $pageleave
    autocapture: true,             // Auto-capture clicks, inputs, form submits
    persistence: 'localStorage+cookie',
    loaded: (ph) => {
      if (process.env.NODE_ENV === 'development') {
        ph.debug();  // Logs all events to console
      }
    },
  });
}
```

### Step 4: Initialize Server SDK (posthog-node)

```typescript
// lib/posthog-server.ts
import { PostHog } from 'posthog-node';

let client: PostHog | null = null;

export function getPostHog(): PostHog {
  if (!client) {
    client = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
      host: process.env.POSTHOG_HOST || 'https://us.i.posthog.com',
      flushAt: 20,           // Send batch when 20 events queued
      flushInterval: 10000,  // Or every 10 seconds
      // The option name is retained by the SDK; pass the feature flags secure API key.
      personalApiKey: process.env.POSTHOG_FEATURE_FLAGS_SECURE_API_KEY,
    });
  }
  return client;
}

// CRITICAL: Flush before process exits (especially in serverless)
export async function shutdownPostHog() {
  if (client) {
    await client.shutdown();
    client = null;
  }
}
```

### Step 5: Initialize Python SDK

```python
import posthog
import os

posthog.project_api_key = os.getenv('NEXT_PUBLIC_POSTHOG_KEY')
posthog.host = os.getenv('POSTHOG_HOST', 'https://us.i.posthog.com')
posthog.personal_api_key = os.getenv('POSTHOG_FEATURE_FLAGS_SECURE_API_KEY')
posthog.debug = os.getenv('NODE_ENV') == 'development'

# Capture an event
posthog.capture('user-123', 'my_event', {'property_key': 'value'})
```

### Step 6: Verify Connection

```typescript
import { getPostHog } from './posthog-server';

async function verifyPostHog() {
  const ph = getPostHog();
  ph.capture({
    distinctId: 'test-setup',
    event: 'posthog_setup_verified',
    properties: { source: 'install-auth-skill' },
  });
  await ph.flush();
  console.log('PostHog event sent — check Activity tab in app.posthog.com');
}

verifyPostHog();
```

## API Key Reference

| Key Type | Prefix | Use | Expose to Client? |
|----------|--------|-----|-------------------|
| Project API Key | `phc_` | Capture events, evaluate flags | Yes (public) |
| Personal API Key | `phx_` | Private API scripts and HogQL queries | Never |
| Feature Flags Secure API Key | project-specific secret | Server-side local flag evaluation | Never |

## API Hosts

| Region | Ingest Host | App Host |
|--------|------------|----------|
| US Cloud | `https://us.i.posthog.com` | `https://us.posthog.com` |
| EU Cloud | `https://eu.i.posthog.com` | `https://eu.posthog.com` |
| Self-hosted | Your domain | Your domain |

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| `posthog.init` ignored | Called server-side | Guard with `typeof window !== 'undefined'` |
| Events not appearing | Wrong API key prefix | Use `phc_` project key for capture |
| `401 Unauthorized` on API | Personal key expired/missing | Generate new key in Settings > Personal API Keys |
| `ECONNREFUSED` | Wrong host URL | Verify US vs EU region in `api_host` |
| Module not found | SDK not installed | Run `npm install posthog-js` or `npm install posthog-node` |

## Output

- Installed PostHog SDK(s) in `node_modules` or `site-packages`
- `.env` file with project and personal API keys
- Initialization code for browser and/or server
- Verified event delivery to PostHog dashboard

## Examples

For a Node service, install `posthog-node`, initialize one long-lived client with the project token and regional ingest host, and add a shutdown path. Add a feature-flags secure key only for server-side local evaluation; use a scoped personal key, project secret key where available, or OAuth for private API calls.

## Resources

See [official PostHog references](references/official-docs.md) for current authority and verification boundaries.

- [PostHog API Overview](https://posthog.com/docs/api)
- [posthog-js Documentation](https://posthog.com/docs/libraries/js)
- [posthog-node Documentation](https://posthog.com/docs/libraries/node)
- [PostHog Python SDK](https://posthog.com/docs/libraries/python)

## Next Steps

After setup, proceed to `posthog-hello-world` for your first event capture.
Files in this package (2)
  • SKILL.md 7 KB
  • references/official-docs.md 1 KB

Versions

RepositoryScoreLicence
This page · jeremylongshore/tons-of-skills-marketplace100MIT
HelixDevelopment/agent100MIT

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version ea3a41637912 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100installing-posthog-in-a-codebase
    Install and configure a PostHog SDK in a repository you can read and edit, following PostHog's docs for the framework. Use when a user working in their codebase asks to add, install, or set up PostHog, product analytics, session replay, or a PostHog SDK. Covers finding the right…
  • 100installing-posthog-in-a-codebase
    Install and configure a PostHog SDK in a repository you can read and edit, following PostHog's docs for the framework. Use when a user working in their codebase asks to add, install, or set up PostHog, product analytics, session replay, or a PostHog SDK. Covers finding the right…
  • 100lucidchart-install-auth
    Choose and configure the correct Lucid authentication model: API key, OAuth user token, or OAuth account token. Use when bootstrapping or repairing Lucid REST access. Trigger with "configure Lucid auth".
  • 100together-install-auth
    Install Together AI SDK v2 and configure a project-scoped API key with least-privilege storage and a read-only model-list verification. Use when connecting a service or workstation to Together AI. Trigger with "Together auth", "install Together SDK", or "TOGETHER_API_KEY setup".
  • 100linear-install-auth
    Install and configure Linear SDK/CLI authentication. Use when setting up a new Linear integration, configuring API keys, or initializing Linear in your project. Trigger with phrases like "install linear", "setup linear", "linear auth", "configure linear API key", "linear SDK setup".
  • 100posthog-sdk-patterns
    Apply production-ready PostHog SDK patterns for TypeScript and Python. Use when implementing PostHog integrations, refactoring SDK usage, or establishing team coding standards for PostHog. Trigger with phrases like "posthog SDK patterns", "posthog best practices", "posthog code…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.