references/react-native.md
React Native error tracking installation - Docs
-
1
Install the package
Required
Install the PostHog React Native library and its dependencies:
PostHog AI
Expo
npx expo install posthog-react-native expo-file-system expo-application expo-device expo-localizationyarn
yarn add posthog-react-native @react-native-async-storage/async-storage react-native-device-info react-native-localize # for iOS cd ios && pod installnpm
npm i -s posthog-react-native @react-native-async-storage/async-storage react-native-device-info react-native-localize # for iOS cd ios && pod install -
2
Configure PostHog
Required
PostHog is most easily used via the
PostHogProvidercomponent. Wrap your app with the provider:App.tsx
PostHog AI
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
usePostHoghook:Component.tsx
PostHog AI
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
errorTrackingwhen setting up PostHog:React Native
PostHog AI
export const posthog = new PostHog('<ph_project_token>', { errorTracking: { autocapture: { uncaughtExceptions: true, unhandledRejections: true, console: ['error', 'warn'], }, }, })Configuration options:
| Option | Description | | --- | --- | | uncaughtExceptions | Captures Uncaught exceptions (ReactNativeGlobal.ErrorUtils.setGlobalHandler) | | unhandledRejections | Captures Unhandled rejections (ReactNativeGlobal.onunhandledrejection) | | console | Captures console logs as errors according to the reported LogLevel |
-
5
Set up error boundaries
Optional
You can use the
PostHogErrorBoundarycomponent to capture rendering errors thrown by components:React Native
PostHog AI
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
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 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
captureExceptionmethod:React Native
PostHog AI
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 native Android and iOS exception capture
- No automatic source map uploads on React Native web
These features will be added in future releases. We recommend you stay up to date with the latest version of the PostHog React Native SDK.
-
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 eventsActivity feed with events
-
8
Upload source maps
Required
Great, you're capturing exceptions! If you serve minified bundles, the next step is to upload source maps to generate accurate stack traces.
Let's continue to the next section.
Community questions
Ask a question
Was this page useful?
HelpfulCould be better