React Native Error Tracking installation

Contents

Install with the wizard

Run this command in your project directory to add PostHog to your React Native project. The wizard detects your framework, installs the SDK, and sets up your first events.

Learn more

Or set it up manually by following the rest of this guide.

  1. Install the package

    Required

    Install the PostHog React Native library and its dependencies:

    npx expo install posthog-react-native expo-file-system expo-application expo-device expo-localization
  2. Configure PostHog

    Required

    PostHog is most easily used via the PostHogProvider component. Wrap your app with the provider:

    App.tsx
    import { PostHogProvider } from 'posthog-react-native'
    export function MyApp() {
    return (
    <PostHogProvider
    apiKey="<ph_project_token>"
    options={{
    host: "https://us.i.posthog.com",
    }}
    >
    <RestOfApp />
    </PostHogProvider>
    )
    }
  3. Send events

    Recommended

    Once installed, PostHog will automatically start capturing events. You can also manually send events using the usePostHog hook:

    Component.tsx
    import { usePostHog } from 'posthog-react-native'
    function MyComponent() {
    const posthog = usePostHog()
    const handlePress = () => {
    posthog.capture('button_pressed', {
    button_name: 'signup'
    })
    }
    return <Button onPress={handlePress} title="Sign Up" />
    }
  4. Set up exception autocapture

    Recommended
    Client-side configuration only

    Support for remote configuration in the error tracking settings requires SDK version 4.35.0 or higher.

    You can autocapture exceptions by configuring the errorTracking when setting up PostHog:

    React Native
    export const posthog = new PostHog('<ph_project_token>', {
    errorTracking: {
    autocapture: {
    uncaughtExceptions: true,
    unhandledRejections: true,
    console: ['error', 'warn'],
    nativeCrashes: true, // native iOS/Android crashes (see below)
    },
    },
    })

    Configuration options:

    OptionDescription
    uncaughtExceptionsCaptures Uncaught exceptions (ReactNativeGlobal.ErrorUtils.setGlobalHandler)
    unhandledRejectionsCaptures Unhandled rejections (ReactNativeGlobal.onunhandledrejection)
    consoleCaptures console logs as errors according to the reported LogLevel
    nativeCrashesCaptures native iOS/Android crashes. Requires @posthog/react-native-plugin and uploaded native symbols (see below)
    Capturing native crashes

    nativeCrashes captures native iOS and Android crashes that the JavaScript layer can't see. Beyond the config above, it needs:

    1. The optional native plugin installed — npx expo install @posthog/react-native-plugin@2 (Expo) or npm i @posthog/react-native-plugin@2 (bare React Native). If it's missing, native capture is a no-op and your JS-level autocapture is unaffected.
    2. Your project's Enable exception autocapture setting enabled in error tracking settings — the same server-side setting that gates JavaScript autocapture.
    3. Native debug symbols uploaded at build time, so crash stack traces are readable. See native crash symbolication.
  5. Set up error boundaries

    Optional

    You can use the PostHogErrorBoundary component to capture rendering errors thrown by components:

    React Native
    import { PostHogProvider, PostHogErrorBoundary } from 'posthog-react-native'
    import { View, Text } from 'react-native'
    const App = () => {
    return (
    <PostHogProvider apiKey="<ph_project_token>">
    <PostHogErrorBoundary
    fallback={YourFallbackComponent}
    additionalProperties={{ screen: "home" }}
    >
    <YourApp />
    </PostHogErrorBoundary>
    </PostHogProvider>
    )
    }
    const YourFallbackComponent = ({ error, componentStack }) => {
    return (
    <View>
    <Text>Something went wrong!</Text>
    <Text>{error instanceof Error ? error.message : String(error)}</Text>
    </View>
    )
    }
    Duplicate errors with console capture

    If you have both PostHogErrorBoundary and console capture enabled in your errorTracking config, render errors will be captured twice. This is because React logs all errors to the console by default. To avoid this, set console: [] on errorTracking.autocapture (for example, errorTracking: { autocapture: { console: [] } }) when using PostHogErrorBoundary.

    Dev mode behavior

    In development mode, React propagates all errors to the global error handler even when they are caught by an error boundary. This means you may see errors reported twice in dev builds. This is expected React behavior and does not occur in production builds.

  6. Manually capture exceptions

    Optional

    You can manually capture exceptions using the captureException method:

    React Native
    try {
    // Your awesome code that may throw
    someRiskyOperation();
    } catch (error) {
    posthog.captureException(error)
    }

    This is helpful if you've built your own error handling logic or want to capture exceptions that are handled by your application code.

  7. Future features

    Optional

    We currently don't support the following features:

    • No automatic source map uploads on React Native web

    This will be added in a future release. We recommend you stay up to date with the latest version of the PostHog React Native SDK.

  8. Verify error tracking

    Recommended
    Confirm events are being sent to PostHog
    Before proceeding, let's make sure exception events are being captured and sent to PostHog. You should see events appear in the activity feed.
    Activity feed with events
    Check for exceptions in PostHog
  9. Upload source maps & native symbols

    Required

    Great, you're capturing exceptions! The next step is to upload source maps (for JavaScript stack traces) and native symbols (for native iOS/Android crash symbolication) so PostHog can generate accurate stack traces.

    Let's continue to the next section.

    Upload source maps & native symbols

iOS dependency resolution for native crash capture

CocoaPods is becoming read-only. CocoaPods has announced the following schedule for its public specs repository:

  • November 2–6, 2026: A read-only dry run will prevent us from publishing new PostHog iOS SDK versions to CocoaPods.
  • December 2, 2026 onward: The repository will be permanently read-only. New PostHog iOS SDK versions will only be available through Swift Package Manager (SPM).

Existing iOS SDK versions will remain available through CocoaPods. To keep receiving iOS SDK updates, migrate the native plugin's posthog-ios dependency to SPM using the hybrid CocoaPods and SPM setup, or use full SPM integration if your app supports it. The hybrid path keeps CocoaPods for the plugin and other React Native dependencies.

This change does not affect @posthog/react-native-plugin releases on npm or Android.

The optional @posthog/react-native-plugin package adds native features such as session replay and native crash capture. Install it as described in the guide for the feature that you use. Then choose one iOS dependency path:

  • CocoaPods. CocoaPods resolves the plugin and posthog-ios. This remains the default path.
  • CocoaPods with posthog-ios through Swift Package Manager. CocoaPods resolves the plugin, and Swift Package Manager resolves posthog-ios. This path needs React Native 0.75 or later and a CocoaPods project with dynamic frameworks.
  • Full Swift Package Manager. React Native's experimental Swift Package Manager integration resolves the plugin and posthog-ios, without CocoaPods. This path needs @posthog/react-native-plugin 2.4.0 or later, Xcode 16 or later, and an iOS 15.1 or later app deployment target.

PostHog verifies the full Swift Package Manager path with an iOS-only React Native 0.87.1 app and React Native Community CLI 20.2.0. This verification does not cover Expo or other React Native versions. Use CocoaPods or the hybrid path unless you validate the full Swift Package Manager path for your configuration.

CocoaPods

Use the standard React Native CocoaPods flow:

Terminal
cd ios
pod install

The plugin podspec adds posthog-ios as a CocoaPods dependency. You do not need to add posthog-ios separately.

CocoaPods with posthog-ios through Swift Package Manager

Add the following property to ios/Podfile.properties.json:

JSON
{
"posthog.useSpm": "true"
}

Add dynamic frameworks to your ios/Podfile:

Ruby
use_frameworks! :linkage => :dynamic

Then install the pods:

Terminal
cd ios
pod install

This setting changes only how the plugin resolves posthog-ios. The plugin and other React Native dependencies still use CocoaPods.

Full Swift Package Manager

This path uses React Native's experimental CocoaPods-free iOS integration. Every native dependency in your app must support React Native's full Swift Package Manager integration. Use CocoaPods or the hybrid path if a dependency does not support it.

Install your JavaScript dependencies first. Make a clean commit or a backup of your iOS project before the conversion. Then run this command from the ios directory:

Terminal
npx react-native spm add --deintegrate --yes

The --deintegrate option removes the complete CocoaPods integration from the iOS project. React Native then finds the plugin's ios/Package.swift manifest. Swift Package Manager resolves the plugin and posthog-ios. Do not run pod install for this path.

PostHog CI verifies this path with the configuration above. The verified app sets its deployment target to iOS 15.1. The plugin package manifest has a separate iOS 15 minimum. The CocoaPods and hybrid paths keep the plugin podspec's iOS 13 minimum.

Still have questions?

Was this page useful?