Installation

Install dependencies and run the Expo app locally on iOS, Android, web, or Expo Go.

This guide takes you from a fresh clone of soar-expo to the app running in an Expo dev server.

Prerequisites

Node.js LTS — use an active LTS release.
pnpm — the template pins packageManager: pnpm@10.32.1.
Xcode — required only for the iOS simulator and local iOS native builds on macOS.
Android Studio — required only for the Android emulator and local Android native builds.
Expo Go or web — useful for the first look, with the native-only caveats below.

You do not need every native toolchain to start. pnpm web runs in a browser, and Expo Go can open a physical-device preview. Purchases, native Google Sign-In, some notification behavior, and config-plugin changes require a development build.

Setup

Clone the template

git clone <repo-url> soar-expo
cd soar-expo

Install dependencies

pnpm install

The lockfile is pnpm-lock.yaml; keep pnpm as the package manager so native module versions stay aligned with Expo SDK 54.

Create your local environment

cp .env.example .env.local

Set the Supabase pair first:

EXPO_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co
EXPO_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

The Supabase client is created at module load time, so the app expects both values. RevenueCat, Google, PostHog, Sentry, links, and update-policy keys can stay blank while you verify the shell.

Start the Expo dev server

pnpm dev

The script runs expo start -c -p 3000, so it clears the Metro cache and uses port 3000. From the Expo terminal press:

i for the iOS simulator.
a for the Android emulator.
w for the web build.

You can also scan the QR code in Expo Go for a physical-device preview.

Development build vs Expo Go

Expo Go is useful for quick UI review, but it does not include every native module this starter uses. Create a development build when you need the actual native runtime:

eas build --profile development --platform ios
eas build --profile development --platform android

Surface	Expo Go / web preview	Development build
Home, Component, Showcase, i18n, theming	Works for UI review	Works
Email auth, todos, profile reads/writes	Works after Supabase is configured	Works
RevenueCat purchases	Not available on web; Expo Go is not the target runtime	Required
Native Google Sign-In	Web no-op; Expo Go is not the target runtime	Required
Apple Sign-In	iOS native only	Required
Push token and notification behavior	Device-dependent; useful only as a rough check	Recommended
Config-plugin changes	Not reflected	Rebuild required

See EAS Build for profiles, channels, and OTA update setup.

Verify the installation

Work through this checklist before adding optional services:

Dev server starts without Metro errors.
Onboarding appears on first launch, then dismisses after completion.
Legal consent modal appears outside the bundled legal screens.
Login screen renders from the drawer or signed-in gates.
Component tab renders signed out and does not need network access.
Home / Showcase / Me render, with signed-in-only rows raising sign-in instead of crashing.
Supabase-backed features can sign in and persist data after the Supabase project is configured and migrations are applied.

Useful scripts

Command	What it does
`pnpm dev`	`expo start -c -p 3000`; press `i`, `a`, or `w`
`pnpm dev:preview`	Start Metro with `APP_VARIANT=preview`
`pnpm dev:prod`	Start Metro with `APP_VARIANT=production`
`pnpm ios`	Start with cache cleared and open the iOS simulator
`pnpm android`	Start with cache cleared and open the Android emulator
`pnpm web`	Start with cache cleared and open the web build
`pnpm typecheck`	Run `tsc --noEmit`
`pnpm lint`	Run `expo lint`
`pnpm format`	Format TS, TSX, JS, JSON, CSS, and Markdown with Prettier
`pnpm gen:types`	Generate `types/database.ts` from Supabase; requires `SUPABASE_PROJECT_ID`
`pnpm clean`	Remove `.expo` and `node_modules`

Common first-run failures

Symptom	Likely cause	Fix
`Missing Supabase environment variables.`	`EXPO_PUBLIC_SUPABASE_URL` or `EXPO_PUBLIC_SUPABASE_ANON_KEY` is missing	Copy `.env.example` to `.env.local` and fill both values
Port `3000` is already in use	Another dev server is running	Stop it or run Expo with another port
Simulator does not open	Xcode command-line tools or simulator runtime missing	Install Xcode, open it once, and install an iOS simulator
Android emulator does not open	Android SDK / emulator not configured	Install Android Studio, create an emulator, and verify `JAVA_HOME` / SDK paths
Stale route, asset, or native-module error	Metro cache	`pnpm dev` already passes `-c`; restart it after env or native config changes
Watchman warnings	Local file watcher state	Restart Watchman or clear its watches
Purchases or Google Sign-In unavailable	Running in Expo Go/web or missing keys	Use a development build and configure the relevant public keys