Create a Mobile App

Create a mobile microapp, download its Expo starter, and run it on your machine. At the end you have a working sign-in, an API of your own, and an app you can extend with your AI assistant.

Prerequisites

A Buildpad project with a running environment, and the Mobile microapps feature switched on for it (see What you need).
Permission to create microapps in the organization.
To download the starter: the right to manage the project. The starter holds the project’s tokens. See Who Can See the Credentials.
Node.js 22 and npm on your computer.
To see the app run: an Android emulator, or the Expo Go app on your phone. On a Mac you can also use the iOS Simulator from Xcode.
An AI IDE such as Claude Code, VS Code with Copilot, Kiro or Antigravity, if you want the AI-assisted workflow. See AI IDE Setup.

Create the microapp

In your project, click Microapps in the sidebar, then click Create Microapp. Enter the Microapp Name and the Description, choose Mobile app in the Type selector, then click Create App.

ℹ️

The type selector only appears when mobile microapps are turned on for the project. Without it you can only create a website.

The selector explains the choice: a Mobile app is a native Android app built with React Native (Expo). It gets its own API, hosted for you, and you download a mobile starter pack to build it. The default, Website, is a Next.js site.

Your app gets a permanent app identifier derived from its name, in the form ai.buildpad.<name>. It is used as the Android package and the iOS bundle identifier. Do not change it once the app is published; stores treat a different identifier as a different app.

Wait for the microapp to finish setting up. Its Detail page shows the source repository and its API’s Amplify app when they are ready.

Download the starter

Open the microapp’s Detail page. In AI IDE Setup, click Download Starter on the card of your AI IDE: VS Code, Kiro, Google Antigravity or Claude Code. Unzip the download and open the folder in your IDE.

The starter is an Expo app with a ready API:

- - index.tsx
  - login.tsx
  - - health+api.ts
- app.json
- amplify.yml
- AGENTS.md
- .env
- .env.local

app/ holds the screens (Expo Router). app/api/ is your API, which runs on Amplify.
server/ is server-only code for the API (sign-in, the DaaS proxy, the list of collections the app may use).
app.json is the app’s configuration, including its name and identifier.
.env and .env.local were generated for you with your project’s real values. The starter also carries MCP settings for your IDE with working credentials.

⚠️

The download contains live credentials (.env.local and your IDE’s MCP configuration). Treat the folder like a password: do not share it or commit those files. They are already listed in .gitignore.

It starts with a working sign-in (the same email and password as your project’s web app), a home screen that checks your API and your session, and a DaaS proxy ready for the collections you add. There is no business data yet; you build that next.

On a Buildpad Engine project, the API signs users in to the Engine, and .env.local also holds the project’s tenant id. The app has no sign-up: create your test users in the Studio’s Users module, and give each one a role in the project. See Mobile apps on a Buildpad Engine project.

Run it

In the starter folder:


npm install
npx expo start

Then choose where to run it:

Press a to open an Android emulator, or
scan the QR code with Expo Go on your phone, or
on a Mac with Xcode, press i to open the iOS Simulator.

Sign in with a Buildpad user of your project. In development the app talks to your local API routes, so edits under app/api/** apply immediately.

To check the deployed API, open <your-api-origin>/api/health in a browser. It shows ok and, under configured, true or false for each group of settings: supabase and daas. If the tenant ID is not set, configured also shows tenant: false. It never shows the values of the settings.

💡

Expo changes between versions. Before you write code that uses an Expo or React Native API, check the documentation for the expo version in package.json at docs.expo.dev . The starter’s AGENTS.md tells your AI assistant to do the same.

Build with your AI assistant

The starter is set up for AI coding assistants. It includes project instructions for your IDE and an MCP configuration with three servers that already hold working credentials:

Server	Use
`daas`	Create collections and fields, manage data and permissions
`buildpad-platform`	Project details and this API’s deployment (environment variables, redeploy, logs)
`buildpad`	Buildpad packages and documentation

Try a prompt such as:

Create an orders collection in DaaS with a title and a status, allow the app to use it, and add a screen that lists and creates orders.

The assistant creates the collection, allows it in server/collections.ts (only listed collections are reachable through the API), and adds the screens.

Before you call a change done, run:


npm run typecheck
npx expo lint
npx expo-doctor

Push to deploy the API

The download is already connected to the microapp’s repository. Commit your work on a branch while you develop. Pushing to main builds and deploys the API on Amplify, so only merge to main when you want the API to change.

Check the API builds tab of the microapp to follow the deployment.

Rules to remember

Add libraries with npx expo install <package>, not npm install <package>. It picks the version that matches your Expo SDK.
android/ and ios/ are generated. Never create, edit or commit them. Change native behaviour in app.json and config plugins instead; the platform generates the native project on every build.
The Android package in app.json is permanent once published.
Secrets belong in the API (app/api, server), never in the app and never in EXPO_PUBLIC_* variables, because the app is shipped to devices.
Never commit a keystore. When builds are enabled the platform keeps the signing key and signs for you.
When your AI assistant uses the platform amplify_* tools, they take the microapp’s id (it is written in AGENTS.md). Without it they act on the project’s main app instead of this one.

When the app works locally, build it for Android. For iPhone and iPad, see iOS.

Troubleshooting

The type selector has no “Mobile app” option. Mobile microapps are not turned on for this project. Contact Buildpad support to turn them on. This is the same on a Supabase project and on a Buildpad Engine project.

Sign-in fails with “Server is not configured: NEXT_PUBLIC_BUILDPAD_TENANT_ID is not set”. The project is a Buildpad Engine project, and the API does not have the project’s tenant id. Locally, download the starter again to get a new .env.local. On Amplify, make sure the variable is set on the microapp’s Amplify app, then redeploy.

Download Starter is disabled. It needs the microapp’s repository to be ready and the project environment to be running. Wait for setup to finish and start the environment if it is stopped.

The download fails with a message that only people who can manage the project can use its credentials. The starter holds the project’s tokens. Only the project’s Admins can download it. Ask a project Admin to give you the Admin role on the project’s Access page. See Roles and Access.

Sign-in fails in the app. Use the same email and password as the project’s web app. Open /api/health on your API. Under configured, a group that shows false (supabase, daas, or tenant on a Buildpad Engine project) has missing settings.

npm install or Expo reports version conflicts. Run npx expo-doctor, and use npx expo install <package> for any package you add.