PostHog Provider

The PostHog provider enables you to manage product analytics, feature flags, and event tracking resources in PostHog using Pulumi. This provider is dynamically bridged from the Terraform PostHog Provider.

Installation

Install the PostHog provider package using your preferred package manager:

bun add pulumi-posthog

pnpm add pulumi-posthog

yarn add pulumi-posthog

npm install pulumi-posthog

Quick Start

import * as pulumi from "@pulumi/pulumi";
import * as posthog from "pulumi-posthog";

// Create a feature flag
const betaFeature = new posthog.FeatureFlag("beta-feature", {
    key: "new-dashboard",
    name: "New Dashboard Beta",
    active: true,
    // filters must be a JSON string, not an object
    filters: JSON.stringify({
        groups: [{
            properties: [],
            rolloutPercentage: 25,
        }],
    }),
});

// Export the feature flag key
export const featureFlagKey = betaFeature.key;

Key Features

The PostHog provider supports the following resources for managing your product analytics infrastructure:

Feature Flags

Create and manage feature flags with advanced targeting and rollout strategies. Perfect for gradual rollouts, A/B testing, and targeted feature releases.

const flag = new posthog.FeatureFlag("premium-feature", {
    key: "premium-features",
    name: "Premium Features",
    active: true,
    filters: JSON.stringify({
        groups: [{
            properties: [{
                key: "plan",
                value: "premium",
                type: "person",
                operator: "exact",
            }],
            rolloutPercentage: 100,
        }],
    }),
});

Dashboards

Build custom dashboards for visualizing your analytics data.

const dashboard = new posthog.Dashboard("analytics", {
    name: "Product Analytics",
    description: "Key metrics for product performance",
    pinned: true,
});

Insights

Configure analytics insights for tracking events, funnels, retention, and other metrics.

const pageviews = new posthog.Insight("pageviews", {
    name: "Pageview Trends",
    queryJson: JSON.stringify({
        kind: "TrendsQuery",
        series: [{
            kind: "EventsNode",
            event: "$pageview",
            name: "Pageviews",
        }],
        dateRange: {
            date_from: "-30d",
        },
    }),
});

Alerts

Set up alerts to monitor metrics and get notified when thresholds are exceeded.

const errorAlert = new posthog.Alert("high-errors", {
    name: "High Error Rate",
    insight: 12345, // Numeric insight ID from PostHog
    enabled: true,
    thresholdType: "absolute",
    thresholdUpper: 100,
    subscribedUsers: [67890], // User IDs to notify
});

Hog Functions

Create custom Hog functions for data transformation and routing.

const transform = new posthog.HogFunction("transform", {
    name: "Custom Event Transform",
    enabled: true,
    type: "transformation",
    hog: `
        fun transform(event) {
            event.properties.processed = true
            return event
        }
    `,
    filtersJson: JSON.stringify({
        events: [{ id: "$pageview" }],
    }),
});

Surveys

Create project-scoped surveys with display conditions, targeting, and iteration scheduling.

const npsSurvey = new posthog.Survey("nps-survey", {
    name: "NPS Q2",
    type: "popover",
    projectId: "12345",
    questionsJson: JSON.stringify([
        {
            type: "rating",
            question: "How likely are you to recommend us?",
            scale: 10,
        },
    ]),
});

External Data Sources

Sync data from external systems (Postgres, Stripe, etc.) into PostHog as warehouse tables.

const stripeSource = new posthog.ExternalDataSource("stripe", {
    sourceType: "Stripe",
    projectId: "12345",
    schemas: ["Customer", "Invoice", "Subscription"],
    syncFrequency: "day",
    // Secrets are redacted on read by PostHog; the planned value is preserved in state.
    jobInputsJson: JSON.stringify({
        stripe_account_id: "acct_123",
        stripe_secret_key: "sk_live_...",
    }),
});

Proxy Records

Provision organization-scoped PostHog reverse-proxy records on custom domains.

const proxy = new posthog.ProxyRecord("marketing-proxy", {
    domain: "analytics.example.com",
});

// After apply, create a CNAME pointing to this target.
export const cnameTarget = proxy.targetCname;

Configuration

See the Configuration guide for detailed setup instructions, including:

Getting your PostHog API key
Setting up Pulumi configuration
Configuring self-hosted PostHog instances
Multi-environment and multi-project setups

Common Use Cases

Feature Rollout Strategy

import * as pulumi from "@pulumi/pulumi";
import * as posthog from "pulumi-posthog";

// Beta feature with gradual rollout
const betaFeature = new posthog.FeatureFlag("beta-checkout", {
    key: "new-checkout",
    name: "New Checkout Experience",
    active: true,
    filters: JSON.stringify({
        groups: [
            {
                // 100% for beta testers
                properties: [{
                    key: "is_beta_tester",
                    value: true,
                    type: "person",
                    operator: "exact",
                }],
                rolloutPercentage: 100,
            },
            {
                // 5% for everyone else
                properties: [],
                rolloutPercentage: 5,
            },
        ],
    }),
});

export const betaFlagKey = betaFeature.key;

Analytics Dashboard

// Create insights
const signupInsight = new posthog.Insight("signups", {
    name: "User Signups",
    queryJson: JSON.stringify({
        kind: "TrendsQuery",
        series: [{
            kind: "EventsNode",
            event: "user_signed_up",
            name: "User Signed Up",
        }],
        dateRange: {
            date_from: "-30d",
        },
    }),
});

// Create dashboard
const dashboard = new posthog.Dashboard("product-dashboard", {
    name: "Product Metrics",
    description: "Key product performance metrics",
    pinned: true,
});

// Set up alert
const signupAlert = new posthog.Alert("signup-alert", {
    name: "Low Signup Alert",
    insight: 12345, // Get insight ID from PostHog
    enabled: true,
    thresholdType: "absolute",
    thresholdLower: 10,
    subscribedUsers: [67890], // Get user IDs from PostHog
});

export const dashboardId = dashboard.dashboardId;

Resource Types

Resource	Description
FeatureFlag	Feature flag management for gradual rollouts and A/B testing
Dashboard	Custom dashboards for data visualization
Insight	Analytics queries and insights
Alert	Metric alerts and notifications
HogFunction	Custom data transformation functions
Survey	Project-scoped surveys with targeting and iteration scheduling
ExternalDataSource	Sync warehouse data from external systems (Postgres, Stripe, etc.)
ProxyRecord	Organization-scoped reverse-proxy records on custom domains