references/EXAMPLE.md
PostHog Expo Example Project
Repository: https://github.com/PostHog/context-mill Path: basics/expo
README.md
Burrito Consideration App (Expo)
A React Native Expo app demonstrating PostHog product analytics integration with modern React Native best practices.
Features
- Product Analytics: Full PostHog integration with event tracking
- Autocapture: Touch events and screen tracking
- Error Tracking: Manual exception capture with
$exceptionevents - User Authentication: Demo login with PostHog user identification
- Session Persistence: AsyncStorage for session management
- Modern React: React 19 with React Compiler for automatic memoization
- File-based Routing: Expo Router for navigation
- New Architecture: Enabled by default for better performance
Project Structure
basics/expo/
├── app/ # Expo Router screens (file-based routing)
│ ├── _layout.tsx # Root layout with PostHogProvider + AuthProvider
│ ├── index.tsx # Home screen (login/welcome)
│ ├── burrito.tsx # Burrito consideration screen
│ └── profile.tsx # User profile screen
├── src/
│ ├── config/
│ │ └── posthog.ts # PostHog client configuration
│ ├── contexts/
│ │ └── AuthContext.tsx # Authentication context with PostHog
│ ├── services/
│ │ └── storage.ts # AsyncStorage wrapper
│ └── styles/
│ └── theme.ts # Shared style constants
├── app.json # Expo configuration
├── babel.config.js # Babel config with React Compiler
├── eslint.config.js # ESLint flat config
├── package.json # Dependencies
├── tsconfig.json # TypeScript strict configuration
└── .env.example # Environment variables template
Getting Started
Prerequisites
- Node.js 18+
- iOS: Xcode (for iOS Simulator)
- Android: Android Studio with emulator
For Android builds: Set environment variables (required):
Add to ~/.zshrc or ~/.bashrc:
# Java from Android Studio (required for Gradle)
export JAVA_HOME="<path-to-android-studio-jdk>"
# Android SDK location
export ANDROID_HOME="$HOME/Library/Android/sdk"
Examples:
export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"export ANDROID_HOME="$HOME/Library/Android/sdk"
Then run source ~/.zshrc to apply.
Installation
-
Install dependencies:
cd basics/expo npm install -
Configure PostHog (optional):
cp .env.example .env # Edit .env with your PostHog project token -
Start the development server:
npx expo start
Running the App
# Start development server
npx expo start
# Run on iOS Simulator
npx expo run:ios
# Run on Android Emulator
npx expo run:android
PostHog Integration
Configuration
PostHog is configured in src/config/posthog.ts using environment variables from app.json:
import Constants from 'expo-constants'
const apiKey = Constants.expoConfig?.extra?.posthogProjectToken
Event Tracking
Events are captured with properties:
posthog.capture('burrito_considered', {
total_considerations: count,
username: user.username,
})
User Identification
Users are identified on login:
posthog.identify(username, {
$set: { username },
$set_once: { first_login_date: new Date().toISOString() },
})
Screen Tracking
Manual screen tracking with Expo Router:
useEffect(() => {
posthog.screen(pathname, {
previous_screen: previousPathname.current,
})
}, [pathname])
Error Tracking
Manual exception capture:
posthog.capture('$exception', {
$exception_type: error.name,
$exception_message: error.message,
$exception_stack_trace_raw: error.stack,
})
Modern React Features
React Compiler
Automatic memoization is enabled via babel-plugin-react-compiler. No need for manual useMemo, useCallback, or React.memo.
React 19 use API
The useAuth hook uses the new use API for context:
export function useAuth() {
const context = use(AuthContext)
if (context === undefined) {
throw new Error('useAuth must be used within an AuthProvider')
}
return context
}
New Architecture
Enabled in app.json for better performance:
{
"expo": {
"newArchEnabled": true
}
}
Building for Production
Use EAS Build for production builds:
# Install EAS CLI
npm install -g eas-cli
# Configure EAS
eas build:configure
# Build for iOS
eas build --platform ios
# Build for Android
eas build --platform android
Performance Debugging
- Press
Jin Expo CLI to open Chrome DevTools - Go to: Profiler > [Gear icon] > "Highlight updates when components render"
- Interact with your app to see which components re-render
Tech Stack
- Expo SDK 54 - Managed workflow
- React 19 - Latest React with Compiler support
- React Native 0.81 - Latest stable
- Expo Router 6 - File-based navigation
- PostHog - Product analytics
- TypeScript - Strict mode enabled
- React Native Reanimated - Smooth animations
- React Native Gesture Handler - Native gestures
License
MIT
.env.example
POSTHOG_PROJECT_TOKEN=phc_your_project_token_here
POSTHOG_HOST=https://us.i.posthog.com
.npmrc
legacy-peer-deps=true
app.config.js
export default {
expo: {
name: 'BurritoApp',
slug: 'burrito-app',
version: '1.0.0',
orientation: 'portrait',
icon: './assets/icon.png',
userInterfaceStyle: 'light',
newArchEnabled: true,
experiments: {
reactCompiler: true,
},
splash: {
image: './assets/splash-icon.png',
resizeMode: 'contain',
backgroundColor: '#333333',
},
ios: {
supportsTablet: true,
bundleIdentifier: 'com.posthog.burritoapp',
},
android: {
adaptiveIcon: {
foregroundImage: './assets/adaptive-icon.png',
backgroundColor: '#333333',
},
package: 'com.posthog.burritoapp',
edgeToEdgeEnabled: true,
},
web: {
favicon: './assets/favicon.png',
},
scheme: 'burritoapp',
extra: {
posthogProjectToken: process.env.POSTHOG_PROJECT_TOKEN,
posthogHost: process.env.POSTHOG_HOST || 'https://us.i.posthog.com',
},
plugins: ['expo-router', 'expo-localization'],
},
}
app/_layout.tsx
import { Stack, usePathname, useGlobalSearchParams } from 'expo-router'
import { useEffect, useRef } from 'react'
import { StatusBar } from 'expo-status-bar'
import { PostHogProvider } from 'posthog-react-native'
import { SafeAreaProvider } from 'react-native-safe-area-context'
import { GestureHandlerRootView } from 'react-native-gesture-handler'
import { AuthProvider } from '../src/contexts/AuthContext'
import { posthog } from '../src/config/posthog'
import { colors } from '../src/styles/theme'
export default function RootLayout() {
const pathname = usePathname()
const params = useGlobalSearchParams()
const previousPathname = useRef<string | undefined>(undefined)
// Manual screen tracking for Expo Router
// @see https://docs.expo.dev/router/reference/screen-tracking/
// React Compiler will auto-optimize this effect
useEffect(() => {
if (previousPathname.current !== pathname) {
posthog.screen(pathname, {
previous_screen: previousPathname.current ?? null,
// Include route params for analytics (filter sensitive data if needed)
...params,
})
previousPathname.current = pathname
}
}, [pathname, params])
return (
<GestureHandlerRootView style={{ flex: 1 }}>
<SafeAreaProvider>
<StatusBar style="light" backgroundColor={colors.headerBackground} />
<PostHogProvider
client={posthog}
autocapture={{
captureScreens: false, // Manual tracking with Expo Router
captureTouches: true,
propsToCapture: ['testID'],
maxElementsCaptured: 20,
}}
>
<AuthProvider>
<Stack
screenOptions={{
headerStyle: { backgroundColor: colors.headerBackground },
headerTintColor: colors.headerText,
headerTitleStyle: { fontWeight: 'bold' },
animation: 'slide_from_right',
}}
>
<Stack.Screen name="index" options={{ title: 'Burrito App' }} />
<Stack.Screen name="burrito" options={{ title: 'Burrito Consideration' }} />
<Stack.Screen name="profile" options={{ title: 'Profile' }} />
</Stack>
</AuthProvider>
</PostHogProvider>
</SafeAreaProvider>
</GestureHandlerRootView>
)
}
app/burrito.tsx
import { useState, useEffect } from 'react'
import { View, Text, TouchableOpacity, StyleSheet } from 'react-native'
import { useRouter } from 'expo-router'
import { usePostHog } from 'posthog-react-native'
import { useAuth } from '../src/contexts/AuthContext'
import { colors, spacing, typography, borderRadius, shadows } from '../src/styles/theme'
/**
* Burrito Consideration Screen
*
* Demonstrates PostHog event tracking with custom properties.
* Each time the user considers a burrito, an event is captured.
*
* @see https://posthog.com/docs/libraries/react-native#capturing-events
*/
export default function BurritoScreen() {
const { user, incrementBurritoConsiderations } = useAuth()
const router = useRouter()
const posthog = usePostHog()
const [hasConsidered, setHasConsidered] = useState(false)
// Redirect to home if not logged in
useEffect(() => {
if (!user) {
router.replace('/')
}
}, [user, router])
if (!user) {
return null
}
const handleConsideration = async () => {
const newCount = user.burritoConsiderations + 1
// Update state first for immediate feedback
await incrementBurritoConsiderations()
setHasConsidered(true)
// Hide success message after 2 seconds
setTimeout(() => setHasConsidered(false), 2000)
// Capture custom event in PostHog with properties
// We recommend using a [object] [verb] format for event names
// @see https://posthog.com/docs/libraries/react-native#capturing-events
posthog.capture('burrito_considered', {
total_considerations: newCount,
username: user.username,
})
}
return (
<View style={styles.container}>
<View style={styles.card}>
<Text style={styles.title}>Burrito Consideration Zone</Text>
<Text style={styles.text}>
Take a moment to truly consider the potential of burritos.
</Text>
{/*
testID is captured by PostHog autocapture for touch events
This helps identify the button in analytics
@see https://posthog.com/docs/libraries/react-native#autocapture
*/}
<TouchableOpacity
style={styles.burritoButton}
onPress={handleConsideration}
activeOpacity={0.8}
testID="consider-burrito-button"
>
<Text style={styles.burritoButtonText}>Consider Burrito</Text>
</TouchableOpacity>
{hasConsidered && (
<View style={styles.successContainer}>
<Text style={styles.success}>Thank you for your consideration!</Text>
<Text style={styles.successCount}>Count: {user.burritoConsiderations}</Text>
</View>
)}
<View style={styles.stats}>
<Text style={styles.statsTitle}>Consideration Stats</Text>
<Text style={styles.statsText}>Total considerations: {user.burritoConsiderations}</Text>
</View>
</View>
</View>
)
}
const styles = StyleSheet.create({
container: {
flex: 1,
backgroundColor: colors.background,
padding: spacing.md,
},
card: {
backgroundColor: colors.cardBackground,
borderRadius: borderRadius.md,
padding: spacing.lg,
...shadows.md,
},
title: {
fontSize: typography.sizes.xl,
fontWeight: typography.weights.bold,
color: colors.text,
marginBottom: spacing.sm,
},
text: {
fontSize: typography.sizes.md,
color: colors.text,
marginBottom: spacing.lg,
lineHeight: 24,
},
burritoButton: {
backgroundColor: colors.burrito,
borderRadius: borderRadius.sm,
padding: spacing.lg,
alignItems: 'center',
marginVertical: spacing.md,
...shadows.sm,
},
burritoButtonText: {
color: colors.white,
fontSize: typography.sizes.lg,
fontWeight: typography.weights.bold,
},
successContainer: {
alignItems: 'center',
marginVertical: spacing.sm,
},
success: {
color: colors.success,
fontSize: typography.sizes.md,
fontWeight: typography.weights.medium,
},
successCount: {
color: colors.success,
fontSize: typography.sizes.lg,
fontWeight: typography.weights.bold,
marginTop: spacing.xs,
},
stats: {
backgroundColor: colors.statsBackground,
padding: spacing.md,
borderRadius: borderRadius.sm,
marginTop: spacing.lg,
},
statsTitle: {
fontSize: typography.sizes.lg,
fontWeight: typography.weights.semibold,
color: colors.text,
marginBottom: spacing.xs,
},
statsText: {
fontSize: typography.sizes.md,
color: colors.text,
},
})
app/index.tsx
import { useState } from 'react'
import {
View,
Text,
TextInput,
TouchableOpacity,
StyleSheet,
ScrollView,
KeyboardAvoidingView,
Platform,
} from 'react-native'
import { useRouter } from 'expo-router'
import { useAuth } from '../src/contexts/AuthContext'
import { colors, spacing, typography, borderRadius, shadows } from '../src/styles/theme'
export default function HomeScreen() {
const { user, login, logout } = useAuth()
const router = useRouter()
const [username, setUsername] = useState('')
const [password, setPassword] = useState('')
const [error, setError] = useState('')
const [isSubmitting, setIsSubmitting] = useState(false)
const handleSubmit = async () => {
setError('')
if (!username.trim() || !password.trim()) {
setError('Please provide both username and password')
return
}
setIsSubmitting(true)
try {
const success = await login(username, password)
if (success) {
setUsername('')
setPassword('')
} else {
setError('An error occurred during login')
}
} catch {
setError('An error occurred during login')
} finally {
setIsSubmitting(false)
}
}
// Logged in view
if (user) {
return (
<ScrollView style={styles.scrollView} contentContainerStyle={styles.scrollContent}>
<View style={styles.card}>
<Text style={styles.title}>Welcome back, {user.username}!</Text>
<Text style={styles.text}>You are now logged in. Feel free to explore:</Text>
<View style={styles.buttonGroup}>
<TouchableOpacity
style={[styles.button, styles.burritoButton]}
onPress={() => router.push('/burrito')}
activeOpacity={0.8}
>
<Text style={styles.buttonText}>Consider Burritos</Text>
</TouchableOpacity>
<TouchableOpacity
style={[styles.button, styles.primaryButton]}
onPress={() => router.push('/profile')}
activeOpacity={0.8}
>
<Text style={styles.buttonText}>View Profile</Text>
</TouchableOpacity>
<TouchableOpacity
style={[styles.button, styles.logoutButton]}
onPress={logout}
activeOpacity={0.8}
>
<Text style={styles.buttonText}>Logout</Text>
</TouchableOpacity>
</View>
</View>
</ScrollView>
)
}
// Login view
return (
<KeyboardAvoidingView
style={styles.container}
behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
>
<ScrollView
style={styles.scrollView}
contentContainerStyle={styles.scrollContent}
keyboardShouldPersistTaps="handled"
>
<View style={styles.card}>
<Text style={styles.title}>Welcome to Burrito Consideration App</Text>
<Text style={styles.text}>Please sign in to begin your burrito journey</Text>
<View style={styles.form}>
<Text style={styles.label}>Username:</Text>
<TextInput
style={styles.input}
value={username}
onChangeText={setUsername}
placeholder="Enter any username"
placeholderTextColor={colors.textLight}
autoCapitalize="none"
autoCorrect={false}
autoComplete="username"
editable={!isSubmitting}
/>
<Text style={styles.label}>Password:</Text>
<TextInput
style={styles.input}
value={password}
onChangeText={setPassword}
placeholder="Enter any password"
placeholderTextColor={colors.textLight}
secureTextEntry
autoComplete="password"
editable={!isSubmitting}
/>
{error ? <Text style={styles.error}>{error}</Text> : null}
<TouchableOpacity
style={[styles.button, styles.primaryButton, isSubmitting && styles.buttonDisabled]}
onPress={handleSubmit}
disabled={isSubmitting}
activeOpacity={0.8}
>
<Text style={styles.buttonText}>{isSubmitting ? 'Signing In...' : 'Sign In'}</Text>
</TouchableOpacity>
</View>
<Text style={styles.note}>
Note: This is a demo app. Use any username and password to sign in.
</Text>
</View>
</ScrollView>
</KeyboardAvoidingView>
)
}
const styles = StyleSheet.create({
container: {
flex: 1,
backgroundColor: colors.background,
},
scrollView: {
flex: 1,
backgroundColor: colors.background,
},
scrollContent: {
flexGrow: 1,
padding: spacing.md,
justifyContent: 'center',
},
card: {
backgroundColor: colors.cardBackground,
borderRadius: borderRadius.md,
padding: spacing.lg,
...shadows.md,
},
title: {
fontSize: typography.sizes.xl,
fontWeight: typography.weights.bold,
color: colors.text,
marginBottom: spacing.sm,
},
text: {
fontSize: typography.sizes.md,
color: colors.text,
marginBottom: spacing.md,
lineHeight: 24,
},
form: {
marginTop: spacing.md,
},
label: {
fontSize: typography.sizes.md,
fontWeight: typography.weights.medium,
color: colors.text,
marginBottom: spacing.xs,
},
input: {
backgroundColor: colors.inputBackground,
borderWidth: 1,
borderColor: colors.border,
borderRadius: borderRadius.sm,
padding: spacing.sm,
fontSize: typography.sizes.md,
color: colors.text,
marginBottom: spacing.md,
},
buttonGroup: {
marginTop: spacing.md,
gap: spacing.sm,
},
button: {
borderRadius: borderRadius.sm,
padding: spacing.md,
alignItems: 'center',
marginTop: spacing.sm,
},
primaryButton: {
backgroundColor: colors.primary,
},
burritoButton: {
backgroundColor: colors.burrito,
},
logoutButton: {
backgroundColor: colors.danger,
},
buttonDisabled: {
opacity: 0.6,
},
buttonText: {
color: colors.white,
fontSize: typography.sizes.md,
fontWeight: typography.weights.semibold,
},
error: {
color: colors.danger,
marginBottom: spacing.sm,
fontSize: typography.sizes.sm,
},
note: {
marginTop: spacing.lg,
color: colors.textSecondary,
fontSize: typography.sizes.sm,
textAlign: 'center',
lineHeight: 20,
},
})
app/profile.tsx
import { useEffect } from 'react'
import { View, Text, TouchableOpacity, StyleSheet, Alert } from 'react-native'
import { useRouter } from 'expo-router'
import { usePostHog } from 'posthog-react-native'
import { useAuth } from '../src/contexts/AuthContext'
import { colors, spacing, typography, borderRadius, shadows } from '../src/styles/theme'
/**
* Profile Screen
*
* Displays user information and demonstrates PostHog error tracking.
* The test error button shows how to capture exceptions manually.
*
* @see https://posthog.com/docs/libraries/react-native#error-tracking
*/
export default function ProfileScreen() {
const { user } = useAuth()
const router = useRouter()
const posthog = usePostHog()
// Redirect to home if not logged in
useEffect(() => {
if (!user) {
router.replace('/')
}
}, [user, router])
if (!user) {
return null
}
/**
* Triggers a test error and captures it in PostHog
*
* This demonstrates manual exception capture using the $exception event.
* In production, you would typically set up automatic exception capture
* or use the before_send callback for customization.
*
* @see https://posthog.com/docs/libraries/react-native#error-tracking
*/
const triggerTestError = () => {
try {
throw new Error('Test error for PostHog error tracking')
} catch (err) {
const error = err as Error
// Capture exception in PostHog
// @see https://posthog.com/docs/error-tracking
posthog.capture('$exception', {
$exception_list: [
{
type: error.name,
value: error.message,
stacktrace: {
type: 'raw',
frames: error.stack ?? '',
},
},
],
$exception_source: 'react-native',
// Additional context
username: user.username,
screen: 'Profile',
})
console.error('Captured error:', error)
Alert.alert('Error Captured', 'The test error has been sent to PostHog!', [{ text: 'OK' }])
}
}
const getJourneyMessage = () => {
const count = user.burritoConsiderations
if (count === 0) {
return "You haven't considered any burritos yet. Visit the Burrito Consideration page to start!"
} else if (count === 1) {
return "You've considered the burrito potential once. Keep going!"
} else if (count < 5) {
return "You're getting the hang of burrito consideration!"
} else if (count < 10) {
return "You're becoming a burrito consideration expert!"
} else {
return 'You are a true burrito consideration master!'
}
}
return (
<View style={styles.container}>
<View style={styles.card}>
<Text style={styles.title}>User Profile</Text>
<View style={styles.stats}>
<Text style={styles.statsTitle}>Your Information</Text>
<View style={styles.infoRow}>
<Text style={styles.infoLabel}>Username:</Text>
<Text style={styles.infoValue}>{user.username}</Text>
</View>
<View style={styles.infoRow}>
<Text style={styles.infoLabel}>Burrito Considerations:</Text>
<Text style={styles.infoValue}>{user.burritoConsiderations}</Text>
</View>
</View>
{/*
testID is captured by PostHog autocapture for touch events
@see https://posthog.com/docs/libraries/react-native#autocapture
*/}
<TouchableOpacity
style={styles.errorButton}
onPress={triggerTestError}
activeOpacity={0.8}
testID="trigger-error-button"
>
<Text style={styles.buttonText}>Trigger Test Error (for PostHog)</Text>
</TouchableOpacity>
<View style={styles.jou