React Native Development on a Cloud Device

How it works

1. 1. Upload a debug build

   Metro can only attach to a debug build — an Android debug .apk or an iOS simulator build. A release build will not work, and this is the most common reason dev fails on the first try. Build it the way you already do, then upload it once; you only repeat this when the native side changes, not when JavaScript changes.

   npm install -g vibeview
   vibeview login
   
   # iOS: run once, then take the .app from DerivedData
   npx react-native run-ios
   vibeview upload-app path/to/YourApp.app
   
   # Android
   cd android && ./gradlew assembleDebug
   vibeview upload-app android/app/build/outputs/apk/debug/app-debug.apk

2. 2. Start Metro, then start the device

   Run Metro as usual, then run vibeview dev from the project root. The first run asks which platform and which uploaded build to use and writes the answer to a vibeview.json in your project, so later runs start immediately. It checks Metro is reachable before creating a session — if Metro is down you get a message rather than a session your app cannot use.

   # terminal 1
   yarn start
   
   # terminal 2
   vibeview dev
   
   # or skip the prompt
   vibeview dev --platform ios --app abc123

3. 3. Edit, save, watch

   The session opens in your browser and hot-reloads on save. Ctrl-C ends it. If Metro stops mid-session the terminal tells you — restart Metro, reload the app in the session, and it picks up where it left off. Because the device is a URL, the same running build can be handed to a designer or a PM without them installing anything.

4. 4. Keep a phone app and a TV app in the same project

   Choices are remembered per platform, so vibeview dev --platform tvos switches to your TV build and asks which app once, while a bare vibeview dev reruns whatever platform you used last. Both live in the same vibeview.json — no config editing to switch between them.

   {
     "defaultPlatform": "android",
     "metroPort": 8081,
     "platforms": {
       "android": { "appId": "myapp-a1b2c3", "deviceCategory": "phone" },
       "androidtv": { "appId": "myapp-tv-d4e5f6" }
     }
   }

5. 5. Match the device architecture

   The build has to match what the cloud device runs: x86_64 for Android, the arm64 simulator slice for iOS. Projects that filter ABIs — common for TV-targeted apps — can produce a build that installs and then refuses to launch, so check this before assuming the upload is at fault.

Full setup instructions live in the documentation.