How to get the mobile app running on your machine, which runtime to use for which kind of change, and the rules every change must follow.
The repository is utopiaspace-mobile. Branch from development. The repository's own README.md and AGENTS.md have the full detail.
Use npm ci for a clean install. Use npm install only when you are changing dependencies.
.envAsk a maintainer for the development Supabase values. Every EXPO_PUBLIC_* value is built into the app and is public, so never put a service-role key or any secret in one.
Then press i for iOS, a for Android, or w for web.
Which way to run the app depends on what you are changing.
| Runtime | Command | Use for |
|---|---|---|
| Expo Go | npx expo start --go -c | Quick checks of screens and logic. It does not include all native settings. |
| Local development build | npx expo run:ios or npx expo run:android, then npx expo start --dev-client -c | Changes to permissions, app links, notifications, or other native behaviour. |
| EAS development build | npx eas-cli@latest build --profile development --platform android | Testing on a physical phone, including push notifications. |
| Web | npm run web | Quick layout checks only. Camera, location, Apple Sign-In, push, and secure storage must be tested on a phone. |
There is no single test command. Run the checks that match your change.
| Folder | Contains |
|---|---|
app/ | Route files. They stay thin and only hand over to a feature screen. |
src/features/ | One folder per feature, each with its screens and an api.ts for data access. |
src/shared/components/ | Shared UI and layout. |
src/shared/lib/ | The Supabase client, notifications, theme, and utilities. |
packages/utopia-ui-native/ | The shared mobile UI package, kept inside this repository. |
android/, ios/ | The native projects. They are committed. |
supabase/ | Database migrations and edge functions. See Database Migrations. |
docs/ | Design notes for individual features. |
From the repository's AGENTS.md. Every change must follow these.
Text component, never Text from React Native.
Import with the @/ alias. No relative paths like ../../.
Reuse existing components. Check React Native Reusables before building new UI.
No new UI or state management libraries without approval.
Keep business logic out of route files in app/.
Use the shared Supabase client from @/shared/lib/supabase.
Use onPress, not onClick.
State is plain React state. There is no Redux or Zustand.
| Problem | Fix |
|---|---|
| Metro or packages behave strangely | npm run clean, then npm ci, then npm run dev. |
@utopia/ui-native cannot be found | Run npm install from the repository root. Do not install a copy of it from npm. |
A .env change does not show | Restart with npm run dev. Changes that affect native settings need a new native build. |
| Sign-in opens but never returns to the app | Check the Supabase URL and key, and that utopiaspace://auth/callback is an allowed redirect in Supabase. |