Guide: Local Dev Setup (Mobile App Stack)

Purpose

To provide a standardized guide for setting up local mobile app environments, ensuring developers can build, run, and debug apps consistently across machines (iOS + Android).

Scope

  • Applies to all mobile projects (React Native, Flutter, Native Android/iOS).
  • Used by Mobile Developers, Full-Stack Developers, and QA Mobile Testers.
  • Covers toolchain setup, project configuration, and environment verification.

Objectives

  • Ensure developers can run the app locally on emulator/device within Day 1–2.
  • Standardize tooling, SDK versions, and configurations.
  • Minimize “it works on my machine” issues.

Step-by-Step Setup Process

Step 1 – Prerequisites

  • Install base tools:
    • Git + SSH key setup
    • Node.js (for React Native) or Dart SDK (for Flutter)
    • Java JDK (11 or required version)
    • Android Studio (with SDK + Emulator)
    • Xcode (for iOS) + Command Line Tools
    • CocoaPods (for iOS RN projects) → sudo gem install cocoapods
    • Device drivers (if testing on physical devices)

Step 2 – Repo & Branch Setup

  • Clone repo:
  • git clone git@github.com:org/mobile-app.git
  • cd mobile-app
  • Checkout development branch:
  • git checkout develop

Step 3 – Dependency Installation

  • For React Native:
  • npm install
  • cd ios && pod install && cd ..
  • For Flutter:
  • flutter pub get

Step 4 – Environment Variables

  • Copy sample env:
  • cp .env.example .env
  • Fill values:
    • API base URL (staging/dev)
    • Auth keys (Firebase, AWS Cognito, etc.)
    • Third-party SDK tokens (Google Maps, Stripe test keys)
  • Store .env in secure vault → never commit to repo.

Step 5 – Run App (Android)

  • Start Android Emulator via Android Studio.
  • For React Native:
  • npm run android
  • For Flutter:
  • flutter run

Step 6 – Run App (iOS)

  • Open .xcworkspace in Xcode (React Native) OR run via Flutter:
  • npm run ios
  • # OR
  • flutter run
  • Ensure proper simulator selected (e.g., iPhone 14).

Step 7 – Verify Setup

  • Confirm app builds without errors.
  • Test login with default dev account.
  • Confirm API call works (via staging backend).
  • Submit test commit + PR to validate repo access & CI/CD integration.

Best Practices

  • Use NVM (for RN) or FVM (Flutter Version Manager) to lock SDK versions.
  • Run lint + format before every commit.
  • Use emulators for consistency, but also test on at least one real device per sprint.
  • Document any new dependencies added for future devs.

Do’s & Don’ts

Do’s

  • Keep Android/iOS SDK versions aligned with project config.
  • Use sample .env.example → never create random env keys.
  • Regularly clean build folders if facing errors (npx react-native-clean-project, flutter clean).

Don’ts

  • Don’t install multiple conflicting SDK versions.
  • Don’t commit .env, Pods/, or node_modules/.
  • Don’t skip pod install on iOS RN projects (causes build failures).

Outcome

  • Developers can set up and run mobile projects locally in 1–2 days.
  • Standardized builds across devices and OS.
  • Directly supports EPIC 1 – Doc 1 (Onboarding SOP) and Doc 2 (Onboarding Kit).