Using PostHog

A guide on installing and configuring PostHog for product analytics, session replay, and error tracking.

PostHog is a product analytics platform with session replay, feature flags, and error tracking.

The EAS CLI integration automates the standard PostHog React Native setup: installing the SDK, creating a PostHog organization and project, and configuring your environment variables. You can also set it up manually and use the rest of this guide unchanged.

What you'll learn

This guide covers integrating PostHog with your Expo project:

• Install and configure PostHog in your React Native app
• Error tracking with source maps and native crash symbolication
• Release tagging, feature flags, and troubleshooting

Install and configure PostHog

import { PostHogProvider } from 'posthog-react-native';
import { Slot } from 'expo-router';

export default function RootLayout() {
  return (
    <PostHogProvider
      apiKey={process.env.EXPO_PUBLIC_POSTHOG_API_KEY}
      options={{
        host: process.env.EXPO_PUBLIC_POSTHOG_HOST,
        enableSessionReplay: false, // set to true if you enabled session replay
        // Capture JS exceptions (remove if you didn't enable error tracking):
        errorTracking: {
          autocapture: { uncaughtExceptions: true, unhandledRejections: true },
        },
        // disabled: __DEV__, // uncomment to stop sending events from development builds
      }}>
      <Slot />
    </PostHogProvider>
  );
}

import { Button } from 'react-native';
import { usePostHog } from 'posthog-react-native';

// Inside a component
const posthog = usePostHog();
<Button title="Send test event" onPress={() => posthog?.capture('test_event')} />

Error tracking

If you enabled error tracking, PostHog symbolicates two separate things, and you set them up independently:

• JavaScript source maps for JS/TS exceptions, including Hermes bytecode. See Source maps.
• Native debug symbols for native Android and iOS crashes (ProGuard/R8 mappings and dSYMs). Optional. See Native crash symbolication.

Source maps

Source maps make JavaScript stack traces (including Hermes bytecode) point to your original source instead of minified output.

First, set up injection so each bundle is tagged for upload. Add this to metro.config.js in your project root (create the file if it doesn't exist):

const { getPostHogExpoConfig } = require('posthog-react-native/metro');

const config = getPostHogExpoConfig(__dirname);

module.exports = config;

If you already customize your Metro config (for example, with NativeWind or in a monorepo), apply your changes to the config object that getPostHogExpoConfig returns instead of calling getDefaultConfig yourself.

PostHog's CLI authenticates with the POSTHOG_CLI_* environment variables that connect set. To upload from your own machine, run posthog-cli login instead.

On EAS Build, the posthog-react-native/expo config plugin uploads source maps automatically during the Android (Gradle) and iOS (Xcode) build phases, so there's no extra command to run.

On EAS Update, over-the-air updates ship only JavaScript, so upload just their source maps after each update (native symbols are fixed at build time). Install PostHog's CLI, then:

dist is the default EAS Update output directory.

name: Publish update
on:
  push:
    branches: ['main']
jobs:
  publish_update:
    name: Publish update
    type: update
    params:
      channel: production
  upload_update_sourcemaps:
    name: Upload OTA source maps to PostHog
    needs: [publish_update]
    environment: production
    steps:
      - uses: eas/checkout
      - uses: eas/install_node_modules
      - name: Export JS bundle and source maps
        run: npx expo export --dump-sourcemap --output-dir dist
      - name: Upload source maps to PostHog
        run: npx --yes @posthog/cli@latest hermes upload --directory dist

Native crash symbolication

Optional. Native crashes (as opposed to JavaScript exceptions) need native debug symbols uploaded at build time. The posthog-react-native/expo plugin can do this during EAS Build once you opt in:

{
  "expo": {
    "plugins": [["posthog-react-native/expo", { "uploadNativeSymbols": true }]]
  }
}

This is one of three pieces required end to end: build-time symbol upload (above), native crash autocapture in your provider, and the exception-autocapture setting in your PostHog project. See PostHog's native crash autocapture for the full setup.

Release tagging

Map each captured event back to a specific over-the-air update by registering super properties from expo-updates:

import { useEffect } from 'react';
import * as Updates from 'expo-updates';
import { usePostHog } from 'posthog-react-native';

function ReleaseTagger() {
  const posthog = usePostHog();

  useEffect(() => {
    posthog?.register({
      expo_update_id: Updates.updateId,
      expo_channel: Updates.channel,
      expo_runtime_version: Updates.runtimeVersion,
    });
  }, [posthog]);

  return null;
}

Render <ReleaseTagger /> inside <PostHogProvider>. Every subsequent capture() carries these properties, so you can filter or group events by expo_update_id in PostHog.

Feature flags

Once the provider is set up, feature flags work with no extra configuration. See PostHog's feature flags for React Native and bootstrapping to avoid a network round-trip on app start.

Manage the integration

Use these commands to manage the integration later:

dashboard opens your linked PostHog project. disconnect removes the Expo-side link only. Your PostHog organization, project, and data are left intact.

Manual setup

connect is a shortcut for the standard PostHog React Native setup. To do it manually, follow PostHog's React Native installation guide, then set EXPO_PUBLIC_POSTHOG_API_KEY and EXPO_PUBLIC_POSTHOG_HOST (plus the POSTHOG_CLI_* variables for source maps). Wrap your app in <PostHogProvider> as shown in Step 2. For source maps, see Source maps.

Troubleshooting

Learn more

• PostHog React Native library
• Product analytics for React Native
• Error tracking for React Native
• Session replay for React Native
• Upload source maps for React Native
• Feature flags for React Native