Quick Start

This guide will help you set up and run the mobile application for development.

Requirements

Before you begin, ensure you have the following installed:

• Expo CLI 
• Node.js LTS release 
• Git 
• Watchman  (required only for macOS or Linux users)
• Pnpm 
• Xcode 16.x (required for iOS development). Check available versions at xcodereleases.com  and install the required 16.x version.
• Xcode Command Line Tools (install after Xcode):

xcode-select --install
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

Then open Xcode once to complete first-time setup (license/components).

• Android Studio  (for Android development)

Installation

1. Clone the repository to your local machine:

git clone https://github.com/cardnexus/cardnexus.git
cd cardnexus

2. Verify root pnpm configuration:

These settings live at the repo root and are required for the mobile app to build and run. They differ from other packages in the monorepo because the card scanner SDK and several native modules require hoisting, overrides, and patches.

Root .npmrc must include at least:

node-linker=hoisted
# ...other monorepo-specific .npmrc entries

Root package.json must include a pnpm section with these keys (other pnpm config can exist alongside):

{
  "pnpm": {
    "overrides": {
      "@repo/mobile>tailwindcss": "3.4.4",
      "rolldown": "1.0.0-rc.1",
      "esbuild": "^0.27.2"
    },
    "onlyBuiltDependencies": ["mongodb-memory-server"],
    "patchedDependencies": {
      "@gorhom/bottom-sheet@5.2.8": "apps/mobile/patches/@gorhom__bottom-sheet@5.2.8.patch",
      "@react-native-firebase/analytics@22.4.0": "apps/mobile/patches/@react-native-firebase__analytics@22.4.0.patch",
      "@react-native-firebase/crashlytics@22.4.0": "apps/mobile/patches/@react-native-firebase__crashlytics@22.4.0.patch",
      "@react-native-menu/menu@1.2.2": "apps/mobile/patches/@react-native-menu__menu@1.2.2.patch",
      "react-native-flash-message@0.4.2": "apps/mobile/patches/react-native-flash-message@0.4.2.patch",
      "react-native-vision-camera@4.7.3": "apps/mobile/patches/react-native-vision-camera+4.7.3.patch",
      "zeego@3.0.6": "apps/mobile/patches/zeego@3.0.6.patch"
    }
  }
}

Include any other monorepo-specific overrides alongside these.

If these entries are missing, mobile builds will fail even if other apps in the monorepo work.

3. Install dependencies:

pnpm install

4. Install iOS dependencies (macOS only):

cd apps/mobile
pnpm pods:install

Run pnpm pods:install again whenever iOS native dependencies change (or after native regeneration).

Environment Setup

1. Create environment files:

# Local (default)
cp .env.example .env.local
 
# Dev
cp .env.example .env.dev
 
# Staging
cp .env.example .env.staging
 
# Production
cp .env.example .env.prod

2. Configure your environment variables in each .env file:

• API_URL - API base URL used by the mobile app
• NEXT_FRONTEND_URL - Frontend URL used for web-linked app flows
• EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY - Clerk publishable key for authentication
• EXPO_PUBLIC_IMAGEKIT_URL - ImageKit CDN base URL
• EXPO_PUBLIC_AMPLITUDE_API_KEY - Amplitude API key for analytics
• MOBILE_DATA_CDN_URL - Mobile data CDN URL (required, non-empty)

Optional:

• BUILD_NUMBER - Native build number override (defaults if omitted)

3. Build-time validation:

• Environment variables are validated at build/start time with Zod schemas in apps/mobile/env.js.
• ENVIRONMENT supports: local, dev, staging, prod.

4. Firebase config files:

• iOS: firebase-config/GoogleService-Info.{env}.plist
• Android: firebase-config/google-services.{env}.json

{env} maps to the selected ENVIRONMENT (local, dev, staging, prod).

Running the App

Prerequisites

From the repository root, install dependencies first (if not already done), then move to mobile:

pnpm install
cd apps/mobile

If you are running on iOS, ensure pods are installed:

pnpm pods:install

Select Native Environment (Required)

Because this is a bare workflow project, environment switching for native app IDs, entitlements, and Firebase files is currently handled by script, not automatic runtime env selection.

Run one of these before pnpm ios/pnpm android:

# Local/dev native setup
pnpm native-env:local
# or
pnpm native-env:dev
 
# Staging native setup
pnpm native-env:staging
 
# Production native setup
pnpm native-env:prod

Important (Bare Workflow)

This is a bare workflow Expo project. Native ios/ and android/ directories are committed to git.

• Do not run expo prebuild casually.
• If native regeneration is required, use pnpm prebuild:regenerate:{env} carefully (dev, staging, prod) and review all native diffs.

Development

# Ensure native env is set first
pnpm native-env:dev
 
# Run on iOS simulator
pnpm ios
 
# Run on Android emulator
pnpm android
 
# Run on physical iOS device
pnpm ios:device
 
# Run on physical Android device
pnpm android:device

Release Configuration Runs (Local Native)

Use these when you need to test Release configuration locally (performance/signing behavior) before CI/App Store/Play Store builds.

# Ensure native env is set first (dev/staging/prod)
pnpm native-env:staging
 
# iOS simulator/device in Release configuration
pnpm ios:release
pnpm ios:device:release
 
# Android emulator/device with release variant
pnpm android:release
pnpm android:device:release

Staging

# Ensure native env is set first
pnpm native-env:staging
 
# Run on iOS
pnpm ios
 
# Run on Android
pnpm android

Production

# Ensure native env is set first
pnpm native-env:prod
 
# Run on iOS
pnpm ios
 
# Run on Android
pnpm android

Environment Variable Approach

ENVIRONMENT-based scripts still exist for build/update flows, but local native run targets are currently switched via pnpm native-env:* scripts.

Building the App

Development Build

# iOS
pnpm build:dev:ios
 
# Android
pnpm build:dev:android

Staging Build

# iOS
pnpm build:staging:ios
 
# Android
pnpm build:staging:android

Production Build

# iOS
pnpm build:prod:ios
 
# Android
pnpm build:prod:android

Development Tools

Database Management

The app uses SQLite with Drizzle ORM. To manage the database:

# Generate migrations
pnpm db:generate
 
# Open Drizzle Studio
pnpm start
# Then press 'd' to open Drizzle Studio

Testing

Unit tests are implemented (for example: src/lib/prices/__tests__/smart-price-storage.test.ts).

# Run unit tests
pnpm test
 
# Run CI-style tests with coverage
pnpm test:ci
 
# Install Maestro (one-time setup)
pnpm install-maestro
 
# Run E2E tests
pnpm e2e-test

Common Issues

1. Metro Bundler Issues

• Clear Metro cache: pnpm start --clear
• Project cache script: pnpm clear-cache
• Full cache reset script: pnpm clear-cache:full

2. MMKV Issues

• Storage is encrypted using key cn.
• If data appears corrupted/stale, clear app data or reinstall the app.

3. Firebase Issues

• Ensure environment-specific Google service files match your selected ENVIRONMENT.
• Verify both iOS (GoogleService-Info.{env}.plist) and Android (google-services.{env}.json) files are present.

4. iOS Build Issues

• Clean build: cd ios && xcodebuild clean
• Reset pods: cd ios && pod deintegrate && pod install

5. Android Build Issues

• Clean build: cd android && ./gradlew clean
• Reset gradle daemon: cd android && ./gradlew --stop

Additional Resources

• Expo Documentation 
• React Native Documentation 
• React Query Documentation 
• Clerk Documentation