Skip to main content

Machine Migration Checklist

This page records the path-sensitive and machine-sensitive checks required to move Android and iOS development or release work to another machine.

Files and settings to verify​

local.properties​

Android Studio or Gradle usually regenerates this file per machine. The important value is:

sdk.dir=/absolute/path/to/Android/sdk

Check these locations:

  • apps/mobile/android/local.properties
  • apps/pos-terminal/android/local.properties

Do not commit machine-specific SDK paths unless the team intentionally wants them tracked.

Shell environment​

Verify these environment variables when Gradle cannot find Java or the Android SDK:

  • JAVA_HOME
  • ANDROID_HOME
  • ANDROID_SDK_ROOT

Node through nvm​

Both React Native apps require Node >=22.11.0. The React Native 0.87.1 upgrade and physical-device smoke test were completed with Node 26.7.0 and Yarn 1.22.22. On a machine that uses nvm:

nvm install 26.7.0
nvm use 26.7.0
node --version
yarn --version

Run the root yarn install --frozen-lockfile only after selecting the Node version so native scripts and the postinstall patch run under the same runtime.

Hardcoded path assumptions​

Repository scripts should prefer relative paths. The current apps/mobile/package.json APK install script is relative and should be safe to move across machines.

Still check machine-local path assumptions in:

  • shell aliases
  • CI/CD scripts
  • Android Studio local settings
  • untracked helper scripts on a developer machine

Migration steps​

  1. Clone the repo to the new machine.
  2. Install Node, Yarn, Java, Android SDK, the required NDK, Xcode, CocoaPods, and CMake.
  3. Select a compatible Node version with nvm, then run yarn install --frozen-lockfile from the monorepo root.
  4. Open Android Studio once so SDK components and local.properties can be created or refreshed.
  5. Verify JAVA_HOME, ANDROID_HOME, and ANDROID_SDK_ROOT.
  6. Verify release keystore location and signing properties.
  7. Run yarn mobile:android for a dev build.
  8. Run yarn mobile:apk or yarn mobile:aab for release packaging.

iOS setup checks​

For mobile iOS work, start from:

cd apps/mobile/ios
pod install

Before running pod install or xcodebuild on a new machine, verify:

  • Xcode has completed first launch and required components are installed.
  • Simulator runtime is installed from Xcode Settings.
  • cmake --version works.
  • The machine can reach GitHub, because some pods are downloaded from GitHub.
  • yarn install was run at the repo root so root postinstall patches are applied.

If xcodebuild reports first-launch or missing plugin issues, run:

xcodebuild -runFirstLaunch

The mobile iOS Podfile contains repo-specific recovery fixes:

  • It disables RNFirebase 26 SPM integration so the pods remain compatible with the project's static linkage.
  • It recreates gRPC-Core.modulemap symlinks under Pods/Headers/Private/grpc and Pods/Headers/Public/grpc.
  • It removes -weak_framework "FirebaseFirestoreInternal" from generated app xcconfigs to avoid link failures.

The root postinstall script runs scripts/patch-react-native-dependencies.js, which patches react-native-date-picker to use the optimized ProGuard configuration required by Android Gradle Plugin 9.

Simulator smoke test:

cd apps/mobile/ios
xcodebuild -workspace BsrPosPlus.xcworkspace -scheme BsrPosPlus -configuration Debug -sdk iphonesimulator CODE_SIGNING_ALLOWED=NO build

Known repo-specific notes​

  • Mobile release packaging is already wired through workspace scripts at the repo root.
  • Root scripts include terminal:android:8082, terminal:apk, and terminal:aab for terminal development and release packaging.
  • apps/pos-terminal/android/app/build.gradle has additional afterEvaluate dependencies for react-native-worklets and react-native-reanimated, so CMake or prefab issues on a new machine are likely to show up there first.
  • apps/mobile/android/app/google-services.json and apps/pos-terminal/android/app/google-services.json exist in the repo, so Firebase config is not purely machine-local.
  • apps/mobile/ios/Podfile includes iOS pod recovery hooks for gRPC and FirebaseFirestoreInternal link issues.
  • Root package.json has a postinstall script that patches react-native-date-picker after dependency install.

First checks when a build fails​

  1. JAVA_HOME points to a real JDK.
  2. sdk.dir points to the installed Android SDK.
  3. The required SDK platform, build-tools, and NDK are installed.
  4. The release keystore path exists and signing secrets are loaded.
  5. Any absolute path in machine-local scripts or aliases still matches the new machine.
  6. For iOS, Xcode first launch is complete, simulator runtime is installed, CMake exists, GitHub is reachable, pod install has completed, and root yarn install has run the postinstall patch.