Mobile Getting Started

Shared Setup

Before starting either client, finish the common workspace setup first:

Install Prerequisites

Ensure your development environment has the necessary tools installed:

Install Node.js 20+
Install pnpm 9+
Install git

Clone Repository

Clone the repository and enter the project root to begin development:

# clone repository
git clone https://github.com/sunshineLixun/easystarter.git your-project-name

# enter project root
cd your-project-name

# remove default origin
git remote remove origin

# add your own origin
git remote add origin https://github.com/your-username/your-project-name.git

# push to origin
git push -u origin main

Install Dependencies

Run the following command to download and install all necessary project dependencies:

pnpm install

Configure mobile env vars

Copy the template file:

cp apps/native/.env.development.local.example apps/native/.env.development.local

Then open apps/native/.env.development.local and fill in the values:

Variable	Local default	Purpose
`EXPO_PUBLIC_SERVER_API_URL`	`http://localhost:3001`	Base URL the app uses to call the server (Hono on Cloudflare Workers, port `3001` in dev).
`EXPO_PUBLIC_WEB_APP_URL`	`http://localhost:3000`	URL of the companion web app — used for auth callbacks, magic links, and shared web routes.
`EXPO_PUBLIC_REVENUECAT_IOS_API_KEY`	`appl_your_revenuecat_ios_key`	RevenueCat iOS SDK public key. Get it from RevenueCat dashboard → Project → API keys. Required for IAP / paywall on iOS. Leave the placeholder if you don't need IAP yet.
`EXPO_PUBLIC_REVENUECAT_ANDROID_API_KEY`	`goog_your_revenuecat_android_key`	RevenueCat Android SDK public key. Same source as above. Required for IAP on Android.
`EXPO_PUBLIC_REVENUECAT_ENTITLEMENT_ID`	`pro`	The entitlement identifier configured in RevenueCat; the app checks this to gate Pro features.

The EXPO_PUBLIC_ prefix means Expo bakes these values into the JS bundle at build time — never put server-side secrets here.

Start the server + Expo together

The native app calls the server at http://localhost:3001, so the server must be running. The easiest path is the combined script (run from repo root):

pnpm dev:native+server

Or run them in separate terminals if you want isolated logs:

pnpm dev:server   # wrangler dev --port=3001
pnpm dev:native   # expo start --clear

Pick a development target

Choose one of the following targets to run the app on:

iOS Simulator (requires macOS + Xcode)
Android Emulator (requires Android Studio)
Expo Go on a physical device

For real-device builds (needed when Expo Go can't host the build — custom native modules, RevenueCat, etc.), use the device-specific scripts:

pnpm dev:ios-device              # build & run on a connected iOS device
pnpm dev:android-device          # build & run on a connected Android device
pnpm dev:ios-device+server       # iOS device + server in parallel
pnpm dev:android-device+server   # Android device + server in parallel

These wrap expo run:ios --device / expo run:android --device from apps/native/package.json.

Real device + ngrok

Physical devices can't reach http://localhost:3001 — they're on a separate network from your Mac. Use ngrok to expose the local server over a public HTTPS URL:

ngrok http 3001

Copy the https://xxxx.ngrok-free.app URL ngrok prints, then update EXPO_PUBLIC_SERVER_API_URL in apps/native/.env.development.local:

EXPO_PUBLIC_SERVER_API_URL=https://xxxx.ngrok-free.app

Restart the Expo dev server after changing the env file so the new URL is picked up.

Mobile & Server Scripts Reference

Root-level scripts that touch mobile or server (defined in the monorepo package.json):

pnpm dev:native — Expo only
pnpm dev:server — server only (port 3001)
pnpm dev:native+server — both, in parallel (recommended for most mobile work)
pnpm dev:ios-device / pnpm dev:android-device — build & install on a real device
pnpm dev:ios-device+server / pnpm dev:android-device+server — device build + server in parallel
pnpm dev — turbo-runs every workspace (web + server + native)

Setup Checklist

Now that App + Server are running, complete these steps in order before building any features:

Configure app.json — replace template identifiers with your own app info
Cloudflare — account credentials and D1 setup
Database — Drizzle ORM + D1 schema and migrations
Email Service — Resend for sign-up verification and password reset (recommended for international audiences)
Phone Sign-In — Alibaba Cloud SMS code sign-in (recommended for China)
Authentication — Better Auth, Google OAuth, Apple Sign-In
Object Storage — Cloudflare R2 for avatars and file uploads
RevenueCat — iOS and Android subscriptions and in-app purchases

To deploy and publish, follow these steps in order:

Deploy Server — deploy Hono server to Cloudflare Workers
Submit to App Stores — EAS build and submit to App Store and Google Play

On this page