posthog-js

posthog-js is PostHog’s official JavaScript SDK for the browser, giving web apps event tracking, autocapture, session recording, feature flags, A/B testing, and in-app surveys through a single client. It ships as the flagship package in the PostHog JS monorepo, which also publishes posthog-node, posthog-react-native, posthog-js-lite, and framework-specific wrappers like @posthog/react and @posthog/next — but posthog-js is the canonical entry point most sites install first.

The SDK is built to work with zero backend code: point it at a PostHog project API key and it starts capturing pageviews, clicks, and form submissions automatically, while exposing a small imperative API (posthog.capture, posthog.identify, posthog.isFeatureEnabled) for custom events and flag checks. Its extension-bundle architecture lazy-loads heavier features like session replay and surveys only when enabled, keeping the base bundle lean for sites that just want analytics.

What You Get

• Autocapture of pageviews, clicks, form submissions, and rageclicks with no manual instrumentation
• Session replay recording via an rrweb-based extension, lazy-loaded only when enabled
• Feature flags and A/B/multivariate experiments evaluated client-side with isFeatureEnabled and getFeatureFlag
• In-app surveys and product tours rendered directly by the SDK
• Exception autocapture that reports uncaught errors and unhandled promise rejections as PostHog events
• Cookieless tracking mode and a consent manager for GDPR/CCPA-compliant deployments
• Web vitals capture with attribution for Core Web Vitals monitoring
• Pluggable integrations for Segment, Sentry, and Crisp/Intercom chat widgets

Common Use Cases

• Instrumenting a SaaS web app for product analytics without hand-writing every tracking call
• Running feature flags and experiments directly in the browser to gate UI variants
• Capturing session replays to debug user-reported bugs or watch real usage sessions
• Sending front-end exceptions and unhandled promise rejections to PostHog alongside product events
• Collecting in-app survey responses and NPS scores tied to identified users

Under The Hood

Architecture The SDK centers on PostHog, the main class defined in posthog-core.ts, which wires together a ConsentManager (consent.ts), PostHogPersistence (posthog-persistence.ts/storage.ts) for storing distinct IDs and properties, a RequestQueue/RetryQueue pair (request-queue.ts, retry-queue.ts) that batches and retries event delivery over request.ts, and a RemoteConfigLoader (remote-config.ts) that fetches project-level flag/feature configuration on init. Heavier capabilities — session replay, surveys, product tours, exception autocapture, web vitals — live under src/extensions/ and are pulled in only when enabled, via a family of alternate entrypoints in src/entrypoints/ (module.es.ts, module.full.es.ts, array.full.ts, etc.) that Rollup compiles into differently-sized bundles depending on which extensions a consumer opts into.

Tech Stack Written in TypeScript (96% of the monorepo) with strict mode enabled, targeting ES5 for broad browser compatibility. The package is built with tsc + Rollup (rollup.config.mjs) inside a pnpm/Turborepo monorepo (turbo.json, pnpm-workspace.yaml) that also builds sibling packages like posthog-node and posthog-react-native from a shared @posthog/core. Session replay builds on rrweb, and the repo ships its own packages/rrweb fork/wrapper alongside the browser SDK.

Code Quality The browser package alone carries 122 test files (Jest for unit tests under src/__tests__, Playwright for browser/e2e coverage), and tsconfig.json enforces strict, noImplicitReturns, and noUnusedParameters. The codebase is cleanly partitioned by concern (core state in top-level src/*.ts, feature extensions under src/extensions/, bundle variants under src/entrypoints/), and CI-aligned checks (build, lint, typecheck, test) are documented in CONTRIBUTING.md as required before opening a PR, backed by Husky pre-commit hooks.

API Design Onboarding is a single posthog.init(apiKey, options) call, after which autocapture starts with zero further code; the imperative surface for custom needs is intentionally small and consistent (capture, identify, isFeatureEnabled, getFeatureFlag, onFeatureFlags). API reference docs are generated straight from the TypeScript source via @microsoft/api-extractor (see the generate-references script), keeping documented signatures in sync with the shipped types, and framework-specific ergonomics are layered on top through separate packages (@posthog/react, @posthog/next, @posthog/nuxt) rather than bloating the core SDK.