Running the Expo app locally | Expo Supabase SaaS Kit

This page takes you from a cloned repository to the Expo app running on a simulator, talking to the same local Supabase stack and the same Next.js server that apps/web uses. It covers the command set, the environment files, and the one thing that trips people up most — which host each device class can actually reach.

Before you start

The native app is a client of your local backend, not a self-contained stack. Three things must already be true.

Installing Xcode alone is not enough for iOS: the iOS platform is a separate download, and without it xcodebuild rejects every simulator — even ones that boot fine on their own. See the simulator exists but Xcode will not build to it for how that failure presents.

You also need Node and pnpm. The root package.json declares engines.node >= 20.10.0 and pins packageManager to pnpm@11.20.0; the preinstall script (tooling/scripts/src/requirements.mjs) additionally hard-fails on Node below 18.18 or pnpm below major 9.

The short path

From the repository root, in three terminals:

# 1 — backend
pnpm run supabase:web:start
# 2 — web app (serves /api/v1 and the pages native links out to)
pnpm dev                # or: pnpm --filter web dev
# 3 — native, first run: compiles and installs a development build
pnpm ios:native        # or: pnpm android:native

The first ios:native / android:native takes several minutes: ios/ and android/ are gitignored, so Expo generates them (prebuild) and then compiles. On every subsequent run, once the development build is installed on the simulator, pnpm start:native is enough — it only starts Metro and connects to the already-installed app.

Command reference

Every native script exists twice: as a package script in apps/native/package.json, and as a root alias in the repo's package.json so you never have to cd. Both columns run the same thing.

Lint and format are repo-wide and already cover native: pnpm lint:fix and pnpm format:fix at the root need no native-specific variant.

Environment files

Expo loads .env files by NODE_ENV mode, highest priority first. For expo start (mode development) the order is:

.env.development.local   →   .env.local   →   .env.development   →   .env

The first file to define a key wins, and real shell environment variables beat all of them. Only apps/native/.env.development is committed; everything ending in .local is gitignored at the repo root (.env*.local).

That split is the whole workflow:

• apps/native/.env.development — committed, shared, safe. It mirrors the safe-to-commit half of apps/web/.env.development.
• apps/native/.env.development.local — yours alone. Create it when you need a personal override (a LAN IP, a different Supabase project). Copy only the keys you are changing; the rest still fall through to the committed file.

What each variable does

Every key in apps/native/.env.development, verified against the code that reads it:

Three team-account flags are read by features/core/config/feature-flags.config.ts but are not present in the committed file, so they fall back to their code defaults: EXPO_PUBLIC_ENABLE_TEAM_ACCOUNTS (default true), EXPO_PUBLIC_ENABLE_TEAM_ACCOUNTS_CREATION (default true), EXPO_PUBLIC_ENABLE_TEAM_ACCOUNTS_ONLY (default false). Add them explicitly if you want to change the shape of the workspace model — docs/native/workspaces.mdoc covers what each one does.

Mirrored values (password policy, feature flags, auth flags) drift silently — native will happily accept a password web rejects. docs/native/config-requirements.mdoc owns the cross-config trigger table; treat it as the checklist whenever you change a NEXT_PUBLIC_* value on web.

Device classes: which host can reach what

This is the part that costs people an afternoon. 127.0.0.1 means something different on every device class, and the committed defaults are not one-size-fits-all — the kit compensates in code for one of the three. If requests are already failing on one platform but not another, the app cannot reach Supabase or the API is the checklist for it.

The Android rewrite, and why it lives in code

10.0.2.2 is Android's fixed alias for the host machine's localhost. The obvious fix is to keep a personal .env.development.local with Android values in it — which then has to be edited back every time you switch to the iOS simulator, and gets stale silently.

Instead, apps/native/features/core/dev-host.ts performs the substitution at the point of use:

export function resolveDevHost(url: string): string {
  if (!__DEV__ || Platform.OS !== 'android') return url;
  return url.replace(
    /^(https?:\/\/)(127\.0\.0\.1|localhost)(?=[:/]|$)/i,
    '$110.0.2.2',
  );
}

Three properties make this safe:

• The __DEV__ guard means the rewrite can never fire in a production build.
• The anchored regex only matches a loopback host. LAN IPs, hostnames and remote URLs pass through untouched, so physical-device testing and staging/production URLs are unaffected.
• It is applied at the two network boundaries — features/core/supabase.ts wraps the client URL with it, and features/core/api-client.ts wraps EXPO_PUBLIC_API_BASE_URL on every fetch. features/auth/components/terms-and-conditions-field.tsx applies it too, because those links open in a browser on the device.

The result: one committed .env.development works on both the iOS simulator and the Android emulator with no override at all.

Opting out. If you use adb reverse tcp:N tcp:N to forward host ports onto the emulator's own loopback, the rewrite gets in the way. Override the URL in .env.development.local with a non-loopback value (your LAN IP) to bypass it — the regex will not match.

Images, and why the rewrite needs an inverse

The Supabase client is not the only thing that hits the network. A React Native <Image source={{ uri }}> fetches directly, bypassing the client entirely — so an avatar URL stored as http://127.0.0.1:54321/... renders as a broken image on the Android emulator. The same module handles it at the render boundary:

export function resolveImageUri(
  uri: string | null | undefined,
): string | undefined {
  if (!uri) return undefined;
  return resolveDevHost(uri);
}

It returns undefined rather than an empty string so callers keep their uri ? <Image /> : null guard. It is applied in features/makerkit/components/workspace-avatar.tsx, app/(home)/user-menu.tsx and app/(home)/(user)/(tabs)/settings/index.tsx.

The inverse matters more. supabase.storage.getPublicUrl() builds its URL from the client's host — which on Android is already 10.0.2.2. Uploading an avatar from the Android emulator would therefore persist http://10.0.2.2:54321/... into your local database, and that row is shared: the web app and the iOS simulator would both render a broken image from then on. features/makerkit/components/picture-controls.tsx reverses the rewrite before persisting:

export function canonicalizeStorageHost(url: string): string {
  if (!__DEV__ || Platform.OS !== 'android') return url;
  return url.replace(/^(https?:\/\/)10\.0\.2\.2(?=[:/]|$)/i, '$1127.0.0.1');
}

Rewrite on the way out, canonicalize on the way in. If you add a screen that either renders a storage URL or writes one back, apply the matching helper. Both failure modes — and how to repair a row already stored with the wrong host — are in images load on one platform only.

Physical device

A phone on your Wi-Fi cannot resolve localhost to your Mac. Find the Mac's LAN address and pin it:

ipconfig getifaddr en0     # Wi-Fi; try en1 if that returns nothing

# apps/native/.env.development.local  (gitignored)
EXPO_PUBLIC_SUPABASE_URL=http://192.168.1.42:54321
EXPO_PUBLIC_API_BASE_URL=http://192.168.1.42:3000
EXPO_PUBLIC_SITE_URL=http://192.168.1.42:3000

Then rebuild onto the device (pnpm ios:native with the device selected, or pnpm android:native with USB debugging on). The device and the Mac must be on the same network, and a macOS firewall prompt for the Node process has to be allowed. Because a LAN IP is not a loopback host, resolveDevHost leaves these values alone on every platform.

Development builds, not Expo Go

The kit is not runnable in Expo Go, and that is a design decision rather than an oversight.

expo-dev-client is a dependency, so expo start targets a development build by default. More fundamentally, apps/native/app.json declares four config plugins — expo-router, expo-secure-store, expo-localization, and expo-image-picker with a custom photosPermission string — and apps/native/app.config.ts conditionally strips an iOS entitlement. Config plugins write into the generated native project at prebuild time: Info.plist permission strings, entitlements, AndroidManifest.xml entries. A pre-compiled, general-purpose Expo Go binary cannot carry project-specific native changes, so the kit's session storage (expo-secure-store), avatar picker and Apple entitlement handling have nowhere to live in it.

The practical consequence is a two-tier reload model.

ios/ and android/ are gitignored: the kit uses continuous native generation, so those directories are build output. Never hand-edit them — expo prebuild --clean deletes them. Express native changes as config-plugin input instead. docs/native/building-shipping.mdoc covers prebuild and EAS in depth.

First-run notes

Two files appear on your first run and should not surprise you.

• apps/native/lib/i18n/messages.generated.ts is generated and committed. start, start:clear, ios and android all run the generator before Expo, so it is refreshed automatically; typecheck runs it in check mode and fails if it is stale. Never hand-edit it — native inherits web's catalogue and keeps only a local delta. See docs/native/i18n.mdoc, and i18n generator and runtime errors for what each generator message means.
• apps/native/uniwind-types.d.ts is generated by Metro on first run, from the dtsFile option in metro.config.js. It is gitignored and referenced from tsconfig.json's include, so a typecheck run before the app has ever been started can report class-name type errors. Start the app once, then typecheck.

Useful local URLs while you work, all from apps/web/supabase/config.toml:

When it doesn't work

Every failure below has a specific fix, and clearing caches at random is not one of them. Troubleshooting the Expo app is organised by symptom; these are the ones you are most likely to hit while getting the app running for the first time.