Documentation › App server connection

Connecting Local App to Server

This guide explains how to configure environment variables, start the Metro bundler, and connect the local development build of the Thumpo app (running on Expo) to the backend server.

1. Overview & Architecture

Thumpo is built with Expo (SDK 58) and custom native modules (modules/thumpo-render for video rendering and modules/thumpo-photos for photo picking). Because of native code dependencies, the app requires a development build rather than standard Expo Go.

Backend services (authentication, template synchronization, credit ledgers, and ElevenLabs AI music generation) are powered by Supabase.

2. Environment Configuration (`.env`)

The app reads public server parameters from environment variables defined in a .env file in the project root.

Create or verify the .env file with the following keys:

EXPO_PUBLIC_SUPABASE_URL=https://<your-project-ref>.supabase.co
EXPO_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_...
EXPO_PUBLIC_GOOGLE_WEB_CLIENT_ID=...
EXPO_PUBLIC_REVENUECAT_ANDROID_KEY=...

Note: All variables beginning with EXPO_PUBLIC_ are embedded into the client code at build/runtime. Never include secret keys (such as Supabase service_role keys) in .env.

Connecting to a Local Supabase Instance

If you are running a local Supabase backend instance (via Supabase CLI):

Android Emulator: Set EXPO_PUBLIC_SUPABASE_URL=http://10.0.2.2:54321 (Android loopback address).
Physical Device on same LAN: Set EXPO_PUBLIC_SUPABASE_URL=http://<your-computer-local-ip>:54321.

3. Building and Launching the Dev App

Option A: Local Android Dev Build (WSL / Local Environment)

To build the native Android debug binary and set up port forwarding:

npm run android:dev

This command runs Expo prebuild, compiles the Kotlin native modules into a debug APK, installs it on your device via adb, and executes adb reverse tcp:8081 tcp:8081.

Option B: EAS Cloud Dev Build

If building via EAS Cloud:

npx eas-cli@latest build --profile development --platform android

Install the output APK link or QR code onto your device.

4. Starting Metro Bundler

In a separate terminal tab, start the Metro bundler:

# Under WSL or with reverse ADB:
npx expo start --localhost

# Or for cross-network access:
npx expo start --tunnel

Why --localhost? When developing under WSL, --localhost forces Metro to listen on IPv4 (127.0.0.1), allowing WSL to relay connection requests cleanly to Windows' adb port forwarding.

5. Connecting Device to Metro & Server Verification

Ensure ADB port forwarding is active: adb reverse tcp:8081 tcp:8081 (or npm run android:metro).
Open the Thumpo app on your Android device or emulator.
In the Expo dev client landing screen, select or enter http://localhost:8081.
Verify backend connectivity by opening Settings › Account in the app to test sign-in or template syncing.