Mobile Apps

Build native mobile apps on top of your Buildpad project. A mobile app signs in with the same users as your web apps, reads and writes the same DaaS data, and gets Android builds from the platform with no build machine of your own.

Two kinds of mobile app

Most of this guide uses the mobile microapp, because it gives you a real native app and a backend to go with it. The build steps are the same for both kinds, and the page shows which one you are looking at.

How it fits together

The app only talks to its own API. The API holds the secrets, signs users in with the project’s sign-in service, and reaches your collections through the DaaS with the signed-in user’s permissions. Nothing secret ships inside the app. On a Supabase project the sign-in service is Supabase. On a Buildpad Engine project it is the Engine, which also serves the data (see Mobile apps on a Buildpad Engine project).

What you need

1. Mobile apps must be turned on for your project. To turn them on, contact Buildpad support. There are two kinds:
   • Mobile microapps add the Mobile app type when you create a microapp, plus its Android and iOS builds.
   • The project mobile app adds the Mobile page to the project sidebar.
2. The Admin role on the project lets you enable mobile builds, start builds and disable them. Other people who can open the project can still open the page and see builds, but the buttons are disabled with a tooltip. A project Admin gives project roles on the project’s Access page. See Roles and Access.

Mobile apps on a Buildpad Engine project

Both kinds of mobile app are available on a Buildpad Engine project. Turning them on, the project Admin role and the builds are the same as on a Supabase project. To see which backend your project uses, read Project Backends.

These things are different on a Buildpad Engine project:

• Sign-in. The API routes of the mobile starter sign users in to the Engine. The Engine also serves the data. The app on the phone calls only its own API, as on a Supabase project.
• Users. The app has no sign-up. An administrator creates each user, with a role in the project, in the Studio’s Users module or through the Engine’s user API. An administrator also resets passwords there. A user with no role in the project cannot sign in.
• Environment. In the starter’s .env.local, NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_BUILDPAD_DAAS_URL hold the Engine URL, NEXT_PUBLIC_SUPABASE_ANON_KEY holds a fixed value that is not a secret, and NEXT_PUBLIC_BUILDPAD_TENANT_ID holds the project’s tenant id. There is no service-role key. .env holds only EXPO_PUBLIC_API_ORIGIN, as on a Supabase project.
• Tenant. The sign-in route sends the project’s tenant id to the Engine. If NEXT_PUBLIC_BUILDPAD_TENANT_ID is not set on the API, GET /api/health shows tenant as not configured, and sign-in answers “Server is not configured”.
• Second factor. The starter has no step for a second factor. A user who has a verified second factor cannot use the app’s data.
• Project mobile app. The shell loads your project’s deployed website. The website signs in to the Engine, as it does in a browser.
• A move to the Buildpad Engine. When you move a Supabase project to the Buildpad Engine, the cutover does not set your mobile microapps to the Buildpad Engine. If the project has mobile microapps, the move page shows Rebuild these mobile apps so they use the Buildpad Engine after the cutover, with the id of each mobile microapp. Rebuild each of these apps. A project mobile app needs no change, because the cutover sets the project’s website to the Buildpad Engine.

Cost and capacity

• Android builds are the low-cost option. A first build of a mobile microapp takes about 15 minutes; later ones are faster.
• iOS builds need an Apple Mac. The platform runs them on bare-metal AWS Mac instances, which are costly. The first iOS build of the day starts a Mac and takes about 25 minutes; later ones take about 5.
• AWS sometimes has no Mac capacity available. When that happens an iOS build waits, and can fail after a long wait. This is not a problem with your app. Retry later, or build on your own Mac (see iOS).

Build iOS on the platform only when you need a build you can hand to someone else, and iterate on your own Mac the rest of the time.

What a build gives you

The platform creates and keeps the Android signing key for you, so every build of an app is signed with the same key and can update the same Play Store listing. Never commit a keystore.

Where to find things

Next steps

Frequently asked

Do I need a Mac? Not for Android. You need a Mac (with Xcode) to run an iOS build, whether you build on the platform or locally. You can still develop and test the app on Android, or in Expo Go, from any computer.

Can I put the iOS app on my iPhone? Not from the platform today. The platform builds a simulator app only. To run on a physical iPhone you build it yourself with your own Apple developer account. See iOS.

Do web changes need a new mobile build? For a mobile microapp, API changes go live when you push to main, with no new build. Changes to the app itself (screens, native settings, icons, plugins) need a new build. For a project mobile app, changes to your website reach users with no build; rebuild only when the native side changes.

How long do build files last? For a limited time, then they expire and the download says so. Build again if you need the file later.

What happens to the signing key if I disable mobile builds? It is kept. You can enable builds again later and keep updating the same app.