Docs / mobile

Add a mobile app to your project

Every project can grow an Expo (React Native) app in the same repository as your web app, using the same database and API.

What you get

Turning mobile on adds a mobile/ folder to your project's repository. Inside it is a working Expo app with file-based routing, one file per screen, and a small client that already knows how to reach your project's API and hold a signed-in user's token.

It is one project, not two — the same repository, the same database, the same API. When you export the project you get both apps together.

Screens are React Native, not web pages: View, Text, FlatList and stylesheets rather than HTML and Tailwind classes. The AI knows this and will not carry web components across.

The Expo SDK version is pinned by the platform. That pin is what lets Expo Go — the app you install on your phone to run the app — open your project at all, so neither you nor the AI should change it.

Turning it on

Open the Mobile tab in the center panel. It is there on every project, including before a mobile app exists.

  1. Click Create the mobile app.
  2. The dialog reads your project and proposes screens: your home page, a login screen when your app has authentication, and your top-level routes. Those arrive ticked.
  3. Below them, under Also found, are screens the platform is less sure about — routes your starter template shipped and screens guessed from your data models. They are offered but not ticked, with a small badge saying where each came from. Tick any you actually want.
  4. Add anything missing in the Add a screen, e.g. Settings field. Each screen becomes one file, shown under its title as mobile/app/<name>.tsx.
  5. Choose how the app signs in. The dialog picks for you: if your web app already has a working sign-in page, the mobile app uses the same login. If it does not, the platform creates a project API key for the app instead, so its screens can read your data from the first run. You can override the choice with the checkbox.
  6. Check the credit line, then click Generate {n} screens.

The credit line reads something like 3 screens · ≈3 credits estimated, metered from actual usage · you have 132.00.

That figure is an estimate, not a price. Every run is charged from the tokens it actually uses, exactly like any other prompt.

If your project has a database but no REST API yet, this step turns the API on first, which adds about a minute before the run starts.

What happens next

Pick one screen and it runs as a single prompt in the chat.

Pick more than one and the scaffold becomes a plan: one step per screen, shown in the chat as a plan card with per-step progress. Each step writes its screen, commits it, and is checked on its own — so if one screen goes wrong, the chain stops there and you retry just that step instead of regenerating everything. Plan mode describes the same machinery in full.

You are not asked to approve the plan a second time: the checklist you just submitted was the approval.

When the run finishes, the Mobile tab shows the app running plus the list of screens it wrote.

Iterating on the app

After the scaffold you change the mobile app the way you change everything else: by prompting.

A target chip appears in the composer showing where your next prompt will land — Auto · Mobile while you are looking at the Mobile tab. Naming a side in the prompt itself always wins over the chip. Working with the AI covers the chip in full.

The eight-screen cap applies to the first run only. More screens are an ordinary follow-up: "add a Settings screen to the mobile app".

What stays on the web

React Native has no server side. It cannot call server components or server actions, so anything that runs on a server stays in the web app and the mobile app calls it over HTTP.

  • API routes, database queries and secrets stay on the web side.
  • The mobile app reaches them through your project's REST API, which the scaffold is wired to use.
  • Values the app itself needs to hold must be named EXPO_PUBLIC_*. Expo writes those into the shipped bundle, so anyone with the app can read them — never put a secret in one.

If a screen needs data that only a server action exposes today, ask for a REST route on the web side first, then point the screen at it.

Limits & notes

  • Up to 8 screens in one scaffold. Add more later from the chat.
  • Screen counts shown before you confirm are estimates; each run is billed from the tokens it used. More screens means more steps, and more steps cost more than one long run would — the trade is that each screen is committed and checked on its own.
  • A project gets one mobile app. Turning it on again is refused — add screens by prompting instead.
  • The project API key ships inside the app bundle, so treat it as public: it can read and write the models your API exposes, and anyone with the app can read it out. Keep sensitive models unexposed in REST API for your data. An app that uses your login instead sends each user's own token, and sees only what that user may see.
  • The Expo SDK version is pinned by the platform so that Expo Go can open your project.
  • Some files belong to the platform and should not be edited by hand or by prompt: .poleved-mobile.json, mobile/app.json, mobile/eas.json, mobile/tsconfig.json, and the API and auth clients in mobile/lib/.
  • The app runs on Android and iOS in Expo Go. Store builds are Android only — see Store builds.
  • Limits may change during alpha.

Related