Composition

Mobile apps

Ship the same app to iOS and Android with the mobile target.

Every composition is a website. The mobile target wraps that website in iOS and Android apps built with Capacitor:

Bash

node scripts/scaffold.mjs --surfaces landing,dashboard --targets mobile \
  --url https://my-app.com --out ../my-app --name my-app

How it works

The native app is a frame around the deployed site, not a second build of it. Its WebView loads --url, so:

pages, auth and API routes run on the server exactly as they do in a browser, with the same cookies and the same code;
every deploy reaches the apps at once, with no store release;
only mobile/index.html is bundled, and it is shown when the site cannot load (no connection, say).

--url is therefore required. --app-id sets the store bundle id; it defaults to the URL's host reversed, so https://my-app.com becomes com.myapp.

capacitor.config.ts with the app id, the app name and the site URL.
mobile/index.html, the offline page.
src/lib/native.ts: isNativeApp() and nativePlatform(), for the few things that should differ inside the app (hiding a "get the app" banner).
@capacitor/core, @capacitor/ios, @capacitor/android and @capacitor/cli, plus cap:sync, cap:ios and cap:android scripts.

Deploy the site first, then create the native projects once and commit them. iOS needs a Mac with Xcode; Android needs Android Studio.

Bash

npx cap add ios
npx cap add android
npm run cap:ios       # opens Xcode
npm run cap:android   # opens Android Studio

Run npm run cap:sync after changing capacitor.config.ts. Icons, splash screens and signing are set in the native projects.

Links to other sites open in the system browser. That includes OAuth providers and Stripe Checkout. Email and password auth stays in the app, because it runs on the site's own routes. Add hosts to server.allowNavigation only if a flow must stay inside the app.
Safe areas. On iOS the config keeps pages clear of the notch and the home indicator (ios.contentInset: "always"); Android does the same by default. If the site sets viewport-fit=cover and pads with env(safe-area-inset-*) itself, switch iOS to "never".
Local development. Point server.url at your machine's LAN address (http://192.168.1.20:3000) and add cleartext: true while testing on a device; do not commit either.
App review. Apple rejects apps that are only a website in a frame (guideline 4.2). Ship something the site alone does not give: push notifications, a wallet pass, offline access to what matters.

Last updated October 17, 2026

Edit this page on GitHub