|
| 1 | +# PostHog Mobile App |
| 2 | + |
| 3 | +React Native mobile app built with Expo and expo-router. |
| 4 | + |
| 5 | +## Quick Start |
| 6 | + |
| 7 | +From the **repository root**: |
| 8 | + |
| 9 | +```bash |
| 10 | +# Install dependencies |
| 11 | +pnpm mobile:install |
| 12 | + |
| 13 | +# Build and run on iOS simulator |
| 14 | +pnpm mobile:run:ios |
| 15 | + |
| 16 | +# Start the development server (after initial build) |
| 17 | +pnpm mobile:start |
| 18 | +``` |
| 19 | + |
| 20 | +## Tech Stack |
| 21 | + |
| 22 | +- [Expo](https://expo.dev) - Build tooling, native APIs, OTA updates |
| 23 | +- [expo-router](https://docs.expo.dev/router/introduction/) - File-based routing |
| 24 | +- [NativeWind](https://www.nativewind.dev/) - Tailwind CSS for React Native |
| 25 | +- [React Query](https://tanstack.com/query) - Async data fetching and caching |
| 26 | +- [Zustand](https://zustand-demo.pmnd.rs/) - Client state management (UI state, selections, local flags) |
| 27 | +- [Phosphor Icons](https://phosphoricons.com/) - Icon library |
| 28 | + |
| 29 | +## Architecture |
| 30 | + |
| 31 | +### Feature Folders |
| 32 | + |
| 33 | +Code is organized by feature in `src/features/`. Each feature is self-contained with its own components, hooks, stores, and API logic. |
| 34 | + |
| 35 | +``` |
| 36 | +src/features/ |
| 37 | +├── auth/ # Authentication & user session |
| 38 | +│ ├── hooks/ |
| 39 | +│ ├── lib/ |
| 40 | +│ ├── stores/ |
| 41 | +│ └── types.ts |
| 42 | +├── chat/ # PostHog AI chat interface |
| 43 | +│ ├── components/ |
| 44 | +│ ├── hooks/ |
| 45 | +│ ├── stores/ |
| 46 | +│ └── types.ts |
| 47 | +├── conversations/ # PostHog AI conversation list & management |
| 48 | +│ ├── api.ts |
| 49 | +│ ├── components/ |
| 50 | +│ ├── hooks/ |
| 51 | +│ └── stores/ |
| 52 | +└── tasks/ # Task management |
| 53 | + ├── api.ts |
| 54 | + ├── components/ |
| 55 | + ├── hooks/ |
| 56 | + └── stores/ |
| 57 | +``` |
| 58 | + |
| 59 | +### File-Based Routing |
| 60 | + |
| 61 | +Routes for the screens are defined by the file structure in `src/app/` using expo-router. |
| 62 | + |
| 63 | +- `(tabs)/` - Parentheses create a layout group (tab navigator) |
| 64 | +- `_layout.tsx` - Configures the navigator for that directory |
| 65 | +- `[id].tsx` - Square brackets define dynamic route parameters |
| 66 | +- Stacks and modals live outside tab group, configured in `_layout.tsx` |
| 67 | + |
| 68 | +``` |
| 69 | +src/app/ |
| 70 | +├── _layout.tsx # Root layout |
| 71 | +├── index.tsx # Entry redirect |
| 72 | +├── auth.tsx # Auth screen (unauthenticated) |
| 73 | +├── (tabs)/ # Tabs group |
| 74 | +│ ├── _layout.tsx # Layout for all tabs |
| 75 | +│ ├── index.tsx # Home tab (Conversations) |
| 76 | +│ ├── tasks.tsx # Tasks tab |
| 77 | +│ └── settings.tsx # Settings tab |
| 78 | +├── chat/ # Chat stack |
| 79 | +│ ├── index.tsx # New chat |
| 80 | +│ └── [id].tsx # Chat by ID (dynamic route) |
| 81 | +└── task/ # Task stack |
| 82 | + ├── index.tsx # New task |
| 83 | + └── [id].tsx # Task by ID (dynamic route) |
| 84 | +``` |
| 85 | + |
| 86 | +### Shared Code |
| 87 | + |
| 88 | +``` |
| 89 | +src/ |
| 90 | +├── components/ # Reusable UI components (Text, etc.) |
| 91 | +└── lib/ |
| 92 | + ├── posthog.ts # Analytics setup |
| 93 | + ├── queryClient.ts # React Query client |
| 94 | + ├── theme.ts # Design tokens |
| 95 | + └── logger.ts # Logger setup |
| 96 | +``` |
| 97 | + |
| 98 | +## Prerequisites |
| 99 | + |
| 100 | +- Node.js 22+ |
| 101 | +- pnpm 10.23.0 |
| 102 | +- Xcode (for iOS development) |
| 103 | +- Android Studio (for Android development) |
| 104 | +- EAS CLI: `npm install -g eas-cli` |
| 105 | + |
| 106 | +## Commands |
| 107 | + |
| 108 | +### From Repository Root |
| 109 | + |
| 110 | +**Development server:** |
| 111 | +```bash |
| 112 | +pnpm mobile:start # Start Expo dev server |
| 113 | +pnpm mobile:start:clear # Start with cleared Metro cache |
| 114 | +``` |
| 115 | + |
| 116 | +**Build and run:** |
| 117 | +```bash |
| 118 | +pnpm mobile:run:ios # iOS simulator |
| 119 | +pnpm mobile:run:ios:device # iOS device (requires Apple Developer account) |
| 120 | +pnpm mobile:run:android # Android emulator/device |
| 121 | +``` |
| 122 | + |
| 123 | +**Native code generation:** |
| 124 | +```bash |
| 125 | +pnpm mobile:prebuild # Generate ios/ and android/ folders |
| 126 | +pnpm mobile:prebuild:clean # Delete and regenerate (when adding native deps) |
| 127 | +``` |
| 128 | + |
| 129 | +**EAS builds:** |
| 130 | +```bash |
| 131 | +pnpm mobile:build:dev # Development build (iOS, cloud) |
| 132 | +pnpm mobile:build:dev:local # Development build (iOS, local) |
| 133 | +pnpm mobile:build:preview # Preview build (iOS) |
| 134 | +pnpm mobile:build:production # Production build (iOS) |
| 135 | +``` |
| 136 | + |
| 137 | +**TestFlight:** |
| 138 | +```bash |
| 139 | +pnpm mobile:testflight # Submit to TestFlight |
| 140 | +``` |
| 141 | + |
| 142 | +**Utilities:** |
| 143 | +```bash |
| 144 | +pnpm mobile:install # Install mobile dependencies |
| 145 | +pnpm mobile:lint # Run Biome check |
| 146 | +pnpm mobile:format # Run Biome format |
| 147 | +``` |
| 148 | + |
| 149 | +### From apps/mobile/ Directory |
| 150 | + |
| 151 | +```bash |
| 152 | +cd apps/mobile |
| 153 | + |
| 154 | +# Development server |
| 155 | +npx expo start |
| 156 | +npx expo start --clear |
| 157 | + |
| 158 | +# Build and run |
| 159 | +npx expo run:ios |
| 160 | +npx expo run:ios --device |
| 161 | +npx expo run:android |
| 162 | +npx expo run:android --device |
| 163 | + |
| 164 | +# Generate native code |
| 165 | +npx expo prebuild |
| 166 | +npx expo prebuild --clean |
| 167 | + |
| 168 | +# EAS builds (iOS) |
| 169 | +npx eas build --profile development --platform ios |
| 170 | +npx eas build --profile development --platform ios --local |
| 171 | +npx eas build --profile preview --platform ios |
| 172 | +npx eas build --profile production --platform ios |
| 173 | + |
| 174 | +# EAS builds (Android) |
| 175 | +npx eas build --profile development --platform android |
| 176 | +npx eas build --profile preview --platform android |
| 177 | +npx eas build --profile production --platform android |
| 178 | + |
| 179 | +# TestFlight |
| 180 | +npx testflight |
| 181 | +npx eas submit --platform ios |
| 182 | + |
| 183 | +# Linting |
| 184 | +pnpm lint |
| 185 | +pnpm lint:fix |
| 186 | +pnpm format |
| 187 | +``` |
| 188 | + |
| 189 | +## Prebuild Explained |
| 190 | + |
| 191 | +`expo prebuild` generates the native `ios/` and `android/` folders from your Expo configuration. |
| 192 | + |
| 193 | +**When to run `prebuild`:** |
| 194 | +- First time setting up the project |
| 195 | +- After adding/removing native dependencies (e.g., `expo-camera`, `react-native-maps`) |
| 196 | +- After changing `app.json` iOS/Android configuration |
| 197 | +- After updating Expo SDK version |
| 198 | + |
| 199 | +**When to use `--clean`:** |
| 200 | +- Switching between Expo SDK versions |
| 201 | +- Native build is failing and you want a fresh start |
| 202 | +- You've made manual changes to native files that you want to discard |
| 203 | + |
| 204 | +The `--clean` flag removes existing `ios/` and `android/` directories before regenerating. |
| 205 | + |
| 206 | +## Build Profiles |
| 207 | + |
| 208 | +Defined in `eas.json`: |
| 209 | + |
| 210 | +| Profile | Purpose | Distribution | |
| 211 | +|---------|---------|--------------| |
| 212 | +| `development` | Dev client with debugging | Internal only | |
| 213 | +| `preview` | Production-like for testing | Internal only | |
| 214 | +| `production` | App Store / Play Store release | Public | |
| 215 | + |
| 216 | +**Local vs Cloud builds:** |
| 217 | +- Cloud (default): Runs on Expo's servers, no local Xcode needed |
| 218 | +- Local (`--local`): Runs on your machine, faster iteration, requires Xcode/Android SDK |
0 commit comments