Skip to main content

​
Start Metro

Metro is the JavaScript bundler for React Native. Start it before running debug builds:
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:
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

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

To create release bundles manually:

​
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:

​
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:
  • 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:
If issues persist, clear Xcode’s derived data:

​
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.