Mobile Application

The mobile application is built with React Native and Expo, featuring authentication, navigation, and dark mode support.

Tech Stack

• React Native with Expo (~54.0)
• React Navigation (native stack)
• NativeWind (Tailwind CSS for React Native)
• Zustand (state management)
• TanStack Query (data fetching)
• Better Auth (authentication)
• Jest + React Native Testing Library (testing)
• EAS Build (builds and deployment)

Prerequisites

• Node.js 24.10.0
• pnpm 10.5.2
• Expo CLI (installed automatically)
• iOS Simulator (for iOS development on macOS)
• Android Studio or Android Emulator (for Android development)

Getting Started

1. Install Dependencies

From the repository root:

pnpm install

2. Environment Setup

Copy the environment file:

cp apps/mobile/.env.example apps/mobile/.env

Edit .env and configure:

EXPO_PUBLIC_API_URL=http://localhost:3000

Platform-specific API URLs

• On iOS simulator: use http://localhost:3000
• On Android emulator: use http://10.0.2.2:3000 or your machine’s IP address
• On physical device: use your computer’s IP address (e.g., http://192.168.1.100:3000)

3. Start Development Server

From the repository root:

pnpm dev:mobile

Or from the mobile folder:

cd apps/mobile
pnpm dev

This will start the Expo development server. You can then:

• Press i to open iOS simulator
• Press a to open Android emulator
• Scan the QR code with Expo Go app on your physical device

Project Structure

apps/mobile/
├── src/
│   ├── app/                 # App-level components
│   │   ├── app-providers.tsx
│   │   └── app-container.tsx
│   ├── features/            # Feature modules
│   │   ├── auth/
│   │   │   ├── screens/
│   │   │   │   ├── login-screen.tsx
│   │   │   │   ├── register-screen.tsx
│   │   │   │   └── reset-password-screen.tsx
│   │   │   ├── components/
│   │   │   │   ├── login-form.tsx
│   │   │   │   └── forgot-password-modal.tsx
│   │   │   └── schemas/
│   │   │       ├── auth.schema.ts
│   │   │       ├── forgot-password.schema.ts
│   │   │       └── reset-password.schema.ts
│   │   ├── home/
│   │   │   ├── home-screen.tsx
│   │   │   └── components/
│   │   │       ├── posts-list.tsx
│   │   │       └── post-card.tsx
│   │   └── profile/
│   │       └── profile-screen.tsx
│   ├── navigation/          # Navigation configuration
│   │   ├── types.ts
│   │   ├── root-navigator.tsx
│   │   └── use-linking.ts
│   ├── components/          # Shared components
│   │   ├── atoms/           # Atomic components
│   │   │   ├── button.tsx
│   │   │   ├── input.tsx
│   │   │   └── password-input.tsx
│   │   ├── organisms/       # Complex components
│   │   │   └── slide-up-modal.tsx
│   │   └── index.ts
│   ├── common/              # Common utilities
│   │   └── hooks/
│   │       ├── use-auth-initialization.ts
│   │       └── use-theme.ts
│   ├── api/                 # API queries
│   │   └── queries/
│   │       └── posts-queries.ts
│   ├── store/               # Zustand stores
│   │   ├── auth-store.ts
│   │   └── theme-store.ts
│   ├── theme/               # Theme configuration
│   │   └── colors.ts
│   ├── i18n/                # Internationalization
│   │   ├── index.ts
│   │   └── config.ts
│   └── lib/                 # External library configs
│       ├── auth-client.ts
│       └── query-client.tsx
├── config/                  # App configuration
│   └── env.config.ts
├── App.tsx                  # App entry point
├── app.config.ts            # Expo configuration
├── eas.json                # EAS Build configuration
└── package.json

Development

Running on Specific Platforms

# iOS
pnpm ios

# Android
pnpm android

# Web (for quick testing)
pnpm web

Type Checking

pnpm typecheck

Linting

pnpm lint

Testing

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

Authentication

The mobile app uses Better Auth with the same configuration as the web apps. Users can:

• Sign up with email and password
• Sign in with email and password
• Sign out
• Reset password via email

Authentication state is managed globally with Zustand and persists across app restarts.

Deep Links (Reset Password)

• Scheme: lonestone://reset-password?token=... (configurable via EXPO_PUBLIC_SCHEME in apps/mobile/.env and CLIENTS_MOBILE_SCHEME in apps/api/.env)
• Important: Expo Go does not support custom schemes; you need a dev build or an installed app with this scheme to test

Testing Deep Links

Prerequisites for testing deep links

Deep links only work with a native build, not with Expo Go. You must run these commands before testing:

1. Generate native projects: pnpm expo prebuild --clean --no-install
2. Install the app on simulator: pnpm expo run:ios

Without these steps, the deep link won’t work!

# 1. Generate native iOS/Android projects with your custom scheme
pnpm expo prebuild --clean --no-install

# 2. Install the dev build on iOS simulator (required!)
pnpm expo run:ios

# 3. Test the deep link (replace "lonestone" with your project's scheme)
xcrun simctl openurl booted "lonestone://reset-password?token=dd8MiuMnEjAJy4JFH4MbBFgq"

# Alternative: Via uri-scheme utility
npx uri-scheme open "lonestone://reset-password?token=YOUR_TOKEN" --ios

Don’t forget to update the scheme!

Make sure to replace lonestone:// with your actual project scheme defined in EXPO_PUBLIC_SCHEME (in apps/mobile/.env).

Example: If your scheme is myapp, use: myapp://reset-password?token=...

Changing the scheme

If you change the scheme, regenerate the prebuild and reinstall the dev build:

pnpm expo prebuild --clean --no-install && pnpm expo run:ios

Universal Links (to be implemented)

The current flow uses a simple deeplink. To switch to Universal Links (iOS) / App Links (Android):

1. Prepare the apple-app-site-association / assetlinks.json files on your domain
2. Use the utility script pnpm create:universallinks to generate the base configuration
3. Update the iOS/Android config (entitlements, manifest) and align the API to send the universal URL

Dark Mode

The app supports automatic dark mode based on system preferences. Users can also toggle dark mode manually using the useTheme hook:

import { useTheme } from '@/common/hooks/use-theme'

function MyComponent() {
  const { colorScheme, toggleColorScheme, isDark } = useTheme()

  return (
    <Button onPress={toggleColorScheme}>
      Toggle {isDark ? 'Light' : 'Dark'} Mode
    </Button>
  )
}

Building

Development Builds

For features that don’t work with Expo Go:

# Build for iOS
eas build --profile development --platform ios

# Build for Android
eas build --profile development --platform android

Install the development build on your device, then start the dev server with pnpm dev.

Preview Builds

For internal testing:

# iOS and Android
eas build --profile preview --platform all

# iOS only
eas build --profile preview --platform ios

# Android only (APK)
eas build --profile preview --platform android

Production Builds

For app store submission:

eas build --profile production --platform all

CI/CD

The mobile app has a dedicated GitHub Actions workflow (.github/workflows/mobile-ci.yml) that:

• Runs linting and type checking
• Executes tests
• Builds preview versions on pull requests
• Builds production versions on main branch pushes

Required secret

Requires EXPO_TOKEN secret in GitHub repository settings.

Troubleshooting

Metro bundler issues

Clear the cache:

pnpm dev --clear

Environment variables not working

1. Restart the Metro bundler after changing .env
2. Ensure variables are prefixed with EXPO_PUBLIC_
3. Check expo-env.d.ts for type declarations

Cannot connect to API

• On iOS simulator: use http://localhost:3000
• On Android emulator: use http://10.0.2.2:3000
• On physical device: use your computer’s IP address (e.g., http://192.168.1.100:3000)