Preview on Your Phone

Your dev build is installed on your phone. Your machine has the source code and a local Supabase running. The last step: connect them.

What “preview” means

When you launch the dev build on your phone, it doesn’t run a frozen JavaScript bundle. Instead, it asks: where can I find a development server to load JS from? That’s where the QR code comes in.

Your laptop runs expo start, which serves the JavaScript bundle on your local network. The QR code encodes the URL of that dev server. Your phone scans it, downloads the bundle over Wi-Fi, and starts running your app — with hot reload as you edit files.

Start the servers

The dashboard’s Preview screen has three controls:

Server	What it does	Default port
Expo dev server	Bundles and serves your React Native code to the dev build	8081
API server	Runs your FastAPI backend locally	8000
Supabase	Local Postgres, Auth, Storage stack	54321-54324

You can start all three with one click. The dashboard streams live output from each so you can see exactly what’s happening.

Note

Both your phone and your laptop must be on the same Wi-Fi network. If you’re on a corporate or coffee-shop network that isolates devices (“client isolation”), the phone won’t be able to reach the laptop. A personal hotspot from your phone is a quick workaround.

Scan the QR code

1. Click Show QR code on the Preview screen. The dashboard renders a QR code based on your laptop’s LAN IP and the Expo dev server port.

2. iPhone: open your Camera app, point it at the QR code, and tap the notification that appears. It opens your dev build.

   Android: open your dev build first, then use its built-in QR scanner from the home screen.

3. The bundle downloads (a few seconds) and your app loads.

What you should see

A working app. The starter has a sign-in screen, a home tab, and a profile tab. You can:

• Sign up with email/password (handled by your local Supabase)
• See your user appear in Supabase Studio at 127.0.0.1:54323
• Make API calls (mediated by your local FastAPI server, talking to Supabase)

If something doesn’t load, the in-app error overlay tells you what went wrong. The most common first-time issues:

• “Network response timed out” — wrong LAN IP. Run “Detect IP” on the Preview screen, or restart your dev server so it picks up the right one.
• “Auth session missing” — Supabase isn’t running. Start it from the Preview screen.
• A red error screen — usually a missing env var. Check that mobile/.env has the values from supabase status.

Hot reload

While both your phone and your laptop are connected, any change you save in mobile/ triggers a re-bundle. Your phone reloads automatically. Most JS-only changes appear in under a second.

For bigger changes (new native modules, app config), you’ll need a new dev build. The Preview screen has a “Rebuild” button that kicks one off.

Reload manually

If the app gets confused (state corruption, stale bundle):

• Shake your phone to bring up the Expo dev menu, then tap Reload
• Or press r in the terminal where the Expo dev server is running

You’re done with the guide

That’s it — you have a working development setup. From here, you’ll spend most of your time in the Blueprint, which is a curated set of features (push notifications, in-app purchases, deep linking, app store submission, and more) with step-by-step instructions for each.

The Blueprint Cards for adding features to your app, one at a time.

Releasing your app When you're ready to submit to the App Store or Play Store.