A working Expo app for Android and iOS that exists to be copied. Out of the box it has every
account flow a real app needs: Password Sign-in, a Second Factor step, Sign-up,
Password Reset and Account Deletion with a recent-Sign-in check, plus a signed-in Home
and Account Screen to build on. Screens never talk to a backend directly. They go through one
narrow Auth Backend seam, and the Starter ships with a Fake Auth Backend, so the whole app
runs, and is tested, before any real service exists. One command, npm run new-app, turns a copy
into a Derived App with its own App Identity and a fresh git history.
See GLOSSARY.md for the project's vocabulary, docs/adr/ for the two architecture decisions, docs/building-on-the-starter.md for turning a copy into your own app, and docs/hand-check.md for the 25-step Android checklist.
Architecture & Development: Burhan Saadi - October 2026
Screens ask useAuth() for everything. AuthProvider is the only code that reaches the Auth
Backend, and the Auth Backend is an interface, so the Fake can be swapped for Firebase Auth,
Supabase or your own server without touching a screen.
graph TD
subgraph Routes [app/ - Expo Router]
AU["(auth) screens<br/>Sign-in Β· Second Factor Β· Sign-up Β· Password Reset"]
AP["(app) screens<br/>Home tab Β· Account tab Β· your screens"]
end
subgraph Shell [Root layout]
RN["RootNavigator<br/>Stack.Protected guards"]
TP["ThemeProvider - light + dark Theme"]
end
subgraph Auth [src/auth - the only way in]
UA["useAuth()"]
PR["AuthProvider<br/>trims input, keeps signed-in state,<br/>turns throws into 'unreachable'"]
SEAM["AuthBackend interface<br/>(src/auth/types.ts)"]
PROV["Provider adapters<br/>Google Β· Apple (switched off)"]
end
subgraph Backends [Swappable]
FAKE["Fake Auth Backend<br/>runs on the phone"]
REAL["Your Auth Backend<br/>Firebase Β· Supabase Β· own server"]
end
subgraph Device [On-device storage]
SS["expo-secure-store<br/>session"]
AS["AsyncStorage<br/>Fake's Accounts"]
end
AU -- "1 Β· Sign in / Sign up / Reset" --> UA
AP -- "1 Β· Sign out / Delete" --> UA
UA --> PR
PR -- "2 Β· Google / Apple sheet" --> PROV
PR -- "3 Β· Typed calls + typed outcomes" --> SEAM
SEAM -- "today" --> FAKE
SEAM -. "your Derived App" .-> REAL
FAKE -- "4 Β· Persist" --> SS
FAKE --> AS
PR -- "5 Β· signed-in / signed-out state" --> RN
RN -- "6 Β· Only the allowed group renders" --> AU
RN --> AP
TP -- "Every color, size and spacing" --> AU
TP --> AP
flowchart TD
L([App launch]) --> SP["Splash stays up while fonts load<br/>and the session is restored"]
SP --> RS{"restoreSession()"}
RS -- "session found" --> H([Home])
RS -- "none, or it threw" --> SI["Sign-in screen<br/>(demo Accounts listed)"]
SI --> V{"Fields valid?"}
V -- "no" --> FE["Field errors, backend not called"] --> SI
V -- "yes" --> PW["signInWithPassword()"]
PW -- "signed-in" --> H
PW -- "second-factor-required" --> SF["Second Factor screen"]
SF -- "wrong-code" --> SF
SF -- "signed-in" --> H
PW -- "wrong-credentials" --> WC["Same message for wrong password<br/>and unknown email"] --> SI
PW -- "confirmation-required" --> CF["Ask to confirm the email"] --> SI
PW -- "rate-limited / unreachable" --> UR["Wait or retry message"] --> SI
H --> AC["Account tab"]
AC -- "Sign out" --> SI
AC -- "Delete account" --> RC{"Signed in within 5 minutes?"}
RC -- "yes" --> DEL["deleteAccount()"] --> SI
RC -- "no: recent-sign-in-required" --> RA["Sign in again<br/>(password, provider, or code)"] --> DEL
- π Every Account Flow, Working β Password Sign-in, Second Factor, Sign-up, Password Reset, Sign-out and Account Deletion are real screens with real error handling, not stubs. A session survives an app restart.
- π One Auth Backend Seam β Screens use
useAuth(); onlyAuthProviderreaches the backend, and the backend is theAuthBackendinterface. Plugging in Firebase Auth, Supabase or your own server means implementing nine methods and changing one export. - π A Fake That Behaves Like a Real Service β The Fake Auth Backend needs no setup, yet it issues Second Factor challenges, enforces a recent Sign-in before Account Deletion, and "sends" a Password Reset that never reveals whether an email has an Account.
- π§Ύ Outcomes Shaped by Real Services β Results such as
confirmation-required(Supabase),recent-sign-in-required(Firebase) andrate-limited(HTTP 429) are already handled on screen, so a real backend only has to map its responses. - π‘οΈ Protected Routes by Construction β
RootNavigatorusesStack.Protected: anything underapp/(app)/is unreachable while signed out, deep links included. A test proves a newly added screen stays locked. - π No Double Submits β Buttons ignore presses while their action runs, and the keyboard's submit shares the same guard. Tapping Sign in twice sends one request.
- π¨ One Theme, Enforced β Every color, font size and spacing value comes from the Theme, in light and dark. A test fails the build if a screen uses a raw value, and a contrast test keeps text at 4.5:1 or better in both modes.
- βΏ Accessible Defaults β Tap targets are 48dp on Android and 44pt on iOS, every field has a visible label that also names the input, and text wraps at the largest system font size.
- 𧬠One-Command Derived Apps β
npm run new-appcopies the Starter, sets the whole App Identity, starts a fresh git history, removes itself, and refuses to finish if anything in the copy still identifies it as the Starter. - π§± No Hand-Edited Native Code β
ios/andandroid/are generated from app.config.ts, so renaming an app or adding Google and Apple Sign-in are config changes, not Xcode and Gradle surgery (ADR 0001).
mobile-app-starter/
βββ app/ # Expo Router routes
β βββ _layout.tsx # Root: ThemeProvider β AuthProvider β RootNavigator, splash
β βββ (auth)/ # Signed-out screens
β β βββ sign-in.tsx # Password Sign-in + Google/Apple buttons + demo Accounts
β β βββ second-factor.tsx # One-time code after a correct password
β β βββ sign-up.tsx # Create an Account
β β βββ password-reset.tsx # "If an account existsβ¦" reset request
β βββ (app)/ # Signed-in only β guarded by Stack.Protected
β βββ _layout.tsx # Signed-in stack; your pushed screens go here
β βββ (tabs)/
β βββ index.tsx # Home β the placeholder for your app's content
β βββ account.tsx # Account Screen: sign out, Account Deletion
βββ src/
β βββ auth/
β β βββ types.ts # The AuthBackend seam: methods + typed outcomes
β β βββ backend.ts # The one line that picks which Auth Backend runs
β β βββ AuthProvider.tsx # The only code that reaches the backend; useAuth()
β β βββ fake/ # Fake Auth Backend + demo Accounts
β β βββ providers/ # Google and Apple native sign-in adapters
β β βββ sign-in-methods.ts # Which Sign-in Methods this platform offers
β β βββ storage.ts # KeyValueStore interface
β β βββ device-storage.ts # SecureStore + AsyncStorage adapters
β β βββ validation.ts # Email and required-field checks
β β βββ password-rules.ts # MIN_PASSWORD_LENGTH β keep in step with your backend
β β βββ messages.ts # Every on-screen auth message in one place
β βββ features/
β β βββ auth/ # DemoAccountsHint Β· ProviderButtons
β β βββ account/ # ReauthPrompt β sign in again before deleting
β βββ navigation/RootNavigator.tsx # Signed-in vs signed-out route groups
β βββ theme/ # Theme (light + dark), fonts, contrast, ThemeProvider
β βββ ui/ # AppText Β· Button Β· TextField Β· FormMessage Β· Screen Β· useSubmit
β βββ test-utils/ # renderApp, test backend, raw-style scanner
βββ tests/flows/ # End-to-end flows through the real routes
βββ scripts/
β βββ new-app.js # The new-app command
β βββ setup-windows.ps1 # What setup-windows.cmd runs
β βββ run-android.js # What run-android.cmd runs
βββ setup-windows.cmd # Windows: install everything the emulator run needs
βββ run-android.cmd # Windows: start the emulator, build and open the app
βββ assets/ # App icon, adaptive icon layers, splash
βββ docs/
β βββ adr/ # 0001 Expo + generated native folders Β· 0002 one Theme
β βββ building-on-the-starter.md # Copied into every Derived App
β βββ hand-check.md # 25-step Android checklist, light and dark
β βββ agents/ # Conventions for Claude Code (issues, domain docs)
βββ app.config.ts # Expo config built from the App Identity + Sign-in Methods
βββ app-identity.json # Name, slug, scheme, bundle ID, package name
βββ GLOSSARY.md # The project's vocabulary
βββ LICENSE # MIT License
βββ README.md # Project presentation (This file)
From the project folder, in Command Prompt or PowerShell:
setup-windows.cmd # once per machine
run-android.cmd # every time you want the app runningsetup-windows.cmdinstalls everything below that's missing: Node.js, git and JDK 17 with winget, then the Android SDK (no Android Studio needed), the emulator, CMake 3.31 and a virtual device. It turns on Windows long paths and the emulator's hardware acceleration after one administrator prompt, setsANDROID_HOMEandJAVA_HOME, and runsnpm install. It's safe to run again. Open a new terminal afterwards if it installed anything.run-android.cmdchecks the machine, runsnpm installwhenpackage-lock.jsonchanged, starts the emulator when no device is attached, generatesandroid/with the long-path fix applied, then builds, installs and opens the app, and leaves Metro running for live reloads.--checkonly lists what's missing,--cleanregeneratesandroid/(after changingapp.config.ts), and--avd <name>picks the emulator.- "System UI isn't responding" on a freshly started emulator during the first build is the emulator struggling under the build's load, not the app. Tap Wait.
- Node.js
^22.13,^24.3or>=26, and git. - The Android SDK, from Android Studio or the command-line tools, plus an emulator or an Android phone with USB debugging on.
ANDROID_HOMEset (usually%LOCALAPPDATA%\Android\Sdk). Add%ANDROID_HOME%\platform-toolstoPATHif you want to typeadbyourself.- JDK 17, with
JAVA_HOMEpointing to it. - Windows only: CMake 3.31 or newer from the SDK, and Windows long paths turned on. See the long-path fix.
- iOS needs a Mac, or a cloud build service such as EAS Build plus a paid Apple Developer Program membership.
- No backend, database or API key. The Fake Auth Backend runs on the phone.
-
Install dependencies:
npm install
-
Build and install the development build:
npx expo run:android
The first run takes several minutes and installs the app on the running emulator or connected phone. Expo Go isn't supported. Use the development build.
-
Iterate:
npx expo start
Reloads your changes into the installed development build.
-
Sign in with
demo@example.com/Password123!. The sign-in screen lists both demo Accounts.
Native build fails on Windows with
ninja: error: mkdir(...)? The build paths passed Windows' 260-character limit.run-android.cmdapplies the fix for you; by hand, install CMake 3.31+, turn on long paths, and pointandroid/local.propertiesat that CMake. The steps are in building-on-the-starter.md.
npm run new-app -- --name "FitTrack" --id com.yourname.fittrack--idbecomes both the iOS bundle ID and the Android package name: at least two dot-separated parts, each starting with a letter, letters and numbers only, no Java reserved words.- Where it goes: a sibling folder named after the slug (here
../fittrack), unless you pass--dir. Pass--slugto choose the slug yourself. - What it does: sets the App Identity (name, slug, URL scheme, bundle ID, package name), starts a fresh git history, removes itself from the copy, fails if anything still identifies the copy as the Starter, and prints a to-do list: icons, Theme, keys and Auth Backend.
- Not copied: the Starter's own plans and issues (
docs/superpowers/,.scratch/), local keys (.env*.local), and build output.
| Block | Job | Lives in | A Derived App⦠|
|---|---|---|---|
| App Identity | Name, slug, scheme, bundle ID, package name | app-identity.json |
Gets its own from npm run new-app |
| Auth Backend seam | Typed methods and outcomes every backend speaks | src/auth/types.ts |
Implements it for its real service |
| Fake Auth Backend | A working backend on the phone, with demo Accounts | src/auth/fake/ |
Replaces it in src/auth/backend.ts |
| AuthProvider | The only caller of the backend; trims input, owns signed-in state | src/auth/AuthProvider.tsx |
Keeps it unchanged |
| Sign-in Methods | Which of Password, Google and Apple are offered | app.config.ts |
Switches Google or Apple on |
| RootNavigator | Shows (auth) or (app), never both |
src/navigation/ |
Keeps it unchanged |
| Theme | Every color, font, size and spacing value, light and dark | src/theme/ |
Replaces the values from its Reference Design |
| UI blocks | Text, buttons, fields, messages, screen frame, submit guard | src/ui/ |
Builds new screens from them |
Screens ask; the provider decides. No screen imports a backend. Everything goes through
useAuth(), which is why the same screens run against the Fake, the test backend, and whatever
real service a Derived App plugs in.
Throws become "unreachable". If a backend or a provider throws, AuthProvider logs the real
error in development ([auth] <action> failed in the Metro log) and the person sees "couldn't reach
the server". The app never crashes on a backend error.
Identity checks are deliberately strict. new-app scans every text file in the copy for the
Starter's name, slug, scheme and IDs, and stops before creating git history if any remain. When the
Starter gains something that carries its identity, scripts/new-app.js must learn about it too.
Everything is configured in app.config.ts, app-identity.json
and an optional .env.local (git-ignored). No native project files are edited by hand.
| Method | Default | Switch on in | Also needs |
|---|---|---|---|
| Password | β On | β | Nothing |
| Off | signInMethods.google = true |
Google Cloud OAuth clients + .env.local keys, then a rebuild |
|
| Apple | Off | signInMethods.apple = true |
A paid Apple Developer Program membership; the button only appears on iPhone |
App Store rule 4.8. An iOS app that offers Google must also offer an equivalent privacy-focused option, usually Sign in with Apple. The Fake accepts any Google or Apple identity without checking it. Your real Auth Backend must verify the ID token.
| Variable | Required? | Default | Purpose |
|---|---|---|---|
EXPO_PUBLIC_GOOGLE_WEB_CLIENT_ID |
Only with Google on | (empty) | Google Web OAuth client ID; the config refuses to build without it when Google is on |
GOOGLE_IOS_URL_SCHEME |
Only for Google on iPhone | (empty) | Reversed iOS client ID; the iOS client ID is derived from it |
Put them in .env.local at the project root, then rebuild with npx expo run:android, because the
native configuration changed. The full walkthrough, including finding your debug SHA-1, is in
building-on-the-starter.md.
While the Fake Auth Backend is active, these Accounts work and the sign-in screen lists them:
| Password | Second Factor code | |
|---|---|---|
demo@example.com |
Password123! |
none |
demo-2fa@example.com |
Password123! |
123456 |
- Your own Accounts created with Sign-up are stored on the phone and survive restarts.
- Deleted demo Accounts come back on the next launch.
- Recent Sign-in lasts 5 minutes. After that, Account Deletion asks you to sign in again, and the 2FA demo Account must enter its code again too.
- Email case and spaces don't matter:
Demo@Example.comis the same Account.
A short tour of the app, taken from the Android hand-check. Run
npx expo run:android first, and try it once in light mode and once in dark.
- Launch. The splash holds until fonts and the session are ready, then shows Sign in with the demo Accounts box.
- Validation. Tap Sign in with empty fields. Field errors appear and nothing is sent.
- Wrong password. "That email and password don't match." The email stays filled in.
- Sign in.
demo@example.com/Password123!, tapped twice quickly: one spinner, and Home appears once. - Restart. Swipe the app away and reopen it. You're still signed in.
- Second Factor. Sign out, then sign in as
demo-2fa@example.com. Enter000000to see the error, then123456to reach Home. - Sign-up and Password Reset. Create an Account (the 8-character rule shows under Password), then request a reset for a known and an unknown email. Both show the same message.
- Account Deletion. Delete a fresh Account straight away. Then make another, wait 5 minutes, and delete it. You're asked to sign in again first.
Look and feel worth showing: every screen in dark mode, the largest system font size (text wraps, nothing is cut off), and the tab bar and status bar clearing the camera cutout and gesture bar.
- Pick.
src/auth/backend.tsexportsauthBackend, which today is the Fake, storing Accounts in AsyncStorage and the session in SecureStore. It also exportsdemoAccounts; set it tonullonce a real backend is in. - Provide.
app/_layout.tsxpasses the backend, the Google and Apple adapters and the enabled Sign-in Methods intoAuthProvider. - Restore. On launch
AuthProvidercallsrestoreSession(). The state goes fromloadingtosigned-inorsigned-out, and the splash hides only when it's no longer loading. - Act. Screens call
useAuth(). Emails and codes are trimmed before they reach the backend, and anything thrown becomesunreachable. - Route.
RootNavigatorrenders(app)only when signed in and(auth)only when signed out, redirecting to/sign-inor/as the state changes.
| Method | Returns | Notes |
|---|---|---|
restoreSession() |
Session | null |
Called once at launch |
signUp(email, password) |
signed-in Β· confirmation-required Β· email-in-use Β· weak-password |
|
signInWithPassword(email, password) |
signed-in Β· second-factor-required Β· confirmation-required Β· wrong-credentials |
Same wrong-credentials for a bad password and an unknown email |
submitSecondFactor(challengeId, code) |
signed-in Β· wrong-code |
Answers challenges from Sign-in and from reauthenticate |
signInWithProvider(identity) |
signed-in |
Google and Apple never ask for a Second Factor |
requestPasswordReset(email) |
sent |
Same answer whether or not the Account exists |
reauthenticate(proof) |
signed-in Β· second-factor-required Β· wrong-credentials |
A fresh signedInAt for Account Deletion |
deleteAccount() |
deleted Β· recent-sign-in-required |
Acts on the current session |
signOut() |
void |
AuthProvider also signs out of Google, so the next person can pick another account |
Every method except restoreSession and signOut can also return unreachable (no network,
timeout) or rate-limited (too many attempts). The mapping from Firebase and Supabase responses is
in building-on-the-starter.md.
One named set of colors, fonts, text sizes and spacing, in light and dark, that every screen takes its look from (ADR 0002).
- Built-in, no styling library. React Native
StyleSheetplus a Theme read fromuseTheme(). NativeWind and component kits like React Native Paper or Tamagui were considered and rejected. - Enforced by a test.
no-raw-style-values.test.tsfails if a screen hard-codes a color, font size or spacing value. - Readable in both modes.
theme.test.tschecks that text stays readable (WCAG 4.5:1 contrast) in light and dark, and that both Themes have the same shape. - Restyling is two files. Hand Claude Code a screenshot or Figma file (a Reference Design) and
ask it to extract the Theme into
src/theme/theme.tsandsrc/theme/fonts.ts. Every screen follows.
The default Theme is a slate palette with IBM Plex Sans, a 4 / 8 / 16 / 24 / 32 spacing scale, and tap targets of 48dp on Android and 44pt on iOS.
npm test # 122 tests, every account flow against the Fake; no emulator needed
npm run typecheck # tsc --noEmit, strict
npm run test:new-app # slow: creates a Derived App, installs it and runs its own testsThe flow tests render the real routes with a test Auth Backend, so they exercise navigation, guards and screens together.
| File | Covers |
|---|---|
| sign-in.test.tsx | Demo Accounts listed, field errors, wrong password, Second Factor, one request per double tap or keyboard submit, restart, Google on/off/cancel, unconfirmed email, rate limits |
| sign-up.test.tsx | Creating an Account, email in use, the password rule, email confirmation |
| password-reset.test.tsx | Empty email, back to Sign-in, one email per double submit |
| account.test.tsx | Sign-out across restarts, cancelled and confirmed Account Deletion, sign in again when old, Google and 2FA re-checks, unreachable server |
| screens.test.tsx | A new (app) screen is locked while signed out and opens when signed in |
| AuthProvider.test.tsx | Session restore, throws β unreachable, trimming, development logging, Google cancel |
| createFakeAuthBackend.test.ts | The Fake's rules: same error for bad password and unknown email, email case, challenges, Sign-up, reset, recent Sign-in |
| theme.test.ts Β· no-raw-style-values.test.ts | Contrast in light and dark; screens use only Theme values |
| Button.test.tsx Β· TextField.test.tsx | Press guard while busy, disabled state, labels and errors |
| app.config.test.ts | App Identity, Google key checks and iOS client ID, Apple plugin, light/dark system UI |
| new-app.test.js Β· new-app.e2e.test.js | Identity derivation, refusing bad folders and IDs, no Starter identity left, a Derived App that installs and passes its own tests |
Before calling a change done on a device, work through docs/hand-check.md on Android: 25 steps, twice (light and dark).
- Swap the Fake before you ship. Implement
AuthBackendon Firebase Auth, Supabase or your own server, export it fromsrc/auth/backend.ts, and setdemoAccountstonull. Never connect the app straight to a database: its password would ship inside the app. - Verify provider tokens server-side. The Fake trusts any Google or Apple identity. A real backend must verify the ID token.
- Keep the password rule in step.
MIN_PASSWORD_LENGTHinsrc/auth/password-rules.tsdrives the Sign-up hint. Match it to your backend's rule. - Generated native folders.
ios/andandroid/are build output and git-ignored. Changeapp.config.tsor a config plugin, never the generated folders. - Development builds only. Once Google Sign-in is in, Expo Go can't run the app.
- Expo SDK. Each Derived App inherits the SDK that was current when it was copied, and upgrades on its own schedule.
- Known unproven areas. iOS is configured but has never been built or run. Google Sign-in is covered by automated tests with a stand-in but has never run against Google. The seam has only run against the Fake. A Derived App inherits these until it proves them.
- Not built, by design. Account linking across Sign-in Methods, lockouts in the Fake, a guard against shipping the Fake, and real Auth Backend adapters.
Copyright 2026 Burhan Saadi. Licensed under the MIT License.
You're free to use, copy, modify, merge, publish, distribute, sublicense and sell this project,
including commercially, and to build your own apps from it. The one condition: keep the copyright
notice and the LICENSE text in any copy or substantial portion you share. Derived Apps
created with npm run new-app carry the LICENSE file with them for this reason.
No warranty, no liability. The software is provided "as is", without warranty of any kind. The author is not liable for any claim, damages or other liability arising from its use. You're responsible for:
- testing it before you rely on it;
- the Auth Backend you plug in, and the security of your users' Accounts and data;
- the keys, accounts and bills of any service you connect (Google Cloud, Apple Developer Program, Firebase, Supabase or others);
- meeting app store rules and the privacy and data-protection laws that apply to your users.
Demo data only. The demo Accounts, emails and codes are fictional and public. Don't reuse them for real Accounts, and don't ship a Derived App with the Fake Auth Backend switched on.
