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.
Or set it up manually by following the rest of this guide.
- 1
Install the package
RequiredInstall the PostHog React Native library and its dependencies:
- 2
Configure PostHog
RequiredPostHog is most easily used via the
PostHogProvidercomponent. Wrap your app with the provider:App.tsx - 3
Send events
RecommendedOnce installed, PostHog will automatically start capturing events. You can also manually send events using the
usePostHoghook:Component.tsx - 4
Set up exception autocapture
RecommendedClient-side configuration onlySupport for remote configuration in the error tracking settings requires SDK version 4.35.0 or higher.
You can autocapture exceptions by configuring the
errorTrackingwhen setting up PostHog:React NativeConfiguration options:
Option Description uncaughtExceptionsCaptures Uncaught exceptions ( ReactNativeGlobal.ErrorUtils.setGlobalHandler)unhandledRejectionsCaptures Unhandled rejections ( ReactNativeGlobal.onunhandledrejection)consoleCaptures console logs as errors according to the reported LogLevelnativeCrashesCaptures native iOS/Android crashes. Requires @posthog/react-native-pluginand uploaded native symbols (see below)Capturing native crashesnativeCrashescaptures native iOS and Android crashes that the JavaScript layer can't see. Beyond the config above, it needs:- The optional native plugin installed —
npx expo install @posthog/react-native-plugin@2(Expo) ornpm 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. - Your project's Enable exception autocapture setting enabled in error tracking settings — the same server-side setting that gates JavaScript autocapture.
- Native debug symbols uploaded at build time, so crash stack traces are readable. See native crash symbolication.
- The optional native plugin installed —
- 5
Set up error boundaries
OptionalYou can use the
PostHogErrorBoundarycomponent to capture rendering errors thrown by components:React NativeDuplicate errors with console captureIf you have both
PostHogErrorBoundaryandconsolecapture enabled in yourerrorTrackingconfig, render errors will be captured twice. This is because React logs all errors to the console by default. To avoid this, setconsole: []onerrorTracking.autocapture(for example,errorTracking: { autocapture: { console: [] } }) when usingPostHogErrorBoundary.Dev mode behaviorIn 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
OptionalYou can manually capture exceptions using the
captureExceptionmethod:React NativeThis 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
OptionalWe 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
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-iosdependency 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-pluginreleases 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-iosthrough Swift Package Manager. CocoaPods resolves the plugin, and Swift Package Manager resolvesposthog-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-plugin2.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:
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:
Add dynamic frameworks to your ios/Podfile:
Then install the pods:
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:
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.







