Skip to main content

​
Start Metro

Metro is the JavaScript bundler for React Native. Start it before running debug builds: 
npm start
Metro listens on port 8932 by default (configured via RCT_METRO_PORT in default.env).
Metro must be running for debug builds. Release builds bundle the JavaScript and don’t need Metro.

​
iOS

​
Setup

Run the setup script from the project root the first time, and again after dependency changes: 
ios/scripts/setup.sh
This installs npm packages, configures Ruby/Bundler, and runs pod install.

​
Build and run

  1. Open ios/sdk-ios-demo.xcworkspace in Xcode.
  2. Select your target device or simulator.
  3. Press Cmd+R to build and run.
Always open the .xcworkspace file, not the .xcodeproj. The workspace includes CocoaPods dependencies.

​
Android

​
Setup

npm install
Then open the android/ directory in Android Studio.

​
Build and run

  1. Let Gradle sync finish (this happens automatically on first open).
  2. Select your target device or emulator.
  3. Click Run (or press Ctrl+R).
Gradle automatically runs adb reverse to forward the Metro port from the device to your machine. No manual port forwarding needed.

​
Build types

DebugRelease
JavaScriptLoaded from Metro (live reload)Bundled into the app binary
Metro requiredYesNo
Use caseDevelopmentProduction / testing
To create release bundles manually: 
# iOS
npm run bundle:ios

# Android
npm run bundle:android

​
Environment configuration

The project reads configuration from environment files in this order:
  1. default.env — Checked into the repo with sensible defaults.
  2. .env — Your local overrides (git-ignored).
Key variables:
VariableDefaultDescription
CHOICELY_APP_KEYDemo app keyYour app key from Choicely Studio
RCT_METRO_PORT8932Metro bundler port
CHOICELY_API_BASEhttps://cloud.choicely.comChoicely API endpoint

​
Troubleshooting

​
Metro not connecting

  • Make sure Metro is running (npm start).
  • iOS simulator: Should connect automatically.
  • Android emulator: Gradle runs adb reverse automatically. If it doesn’t work, run manually: 
    adb reverse tcp:8932 tcp:8932
  • Physical device: Ensure your device and computer are on the same Wi-Fi network.

​
Pod install fails

Re-run the full setup script to start from a clean state: 
ios/scripts/setup.sh
If issues persist, clear Xcode’s derived data: 
rm -rf ios/.build/DerivedData-iOS

​
Component not found

  • Verify the component is added to componentMapping in rn/src/index.js.
  • Confirm the key matches the URL path exactly (e.g. my_component for choicely://special/rn/my_component).
  • Restart Metro after adding new components.