Live Development

Run your React Native app on a VibeView device while you develop — edits on your machine hot-reload on the streamed device in about a second.

Existing Expo app? Three commands. From your project root:

npx vibeview login   # opens your browser to sign in
npx expo start       # Metro, in a second terminal (or let vibeview dev start it)
npx vibeview dev     # first run: accept the detected build command

The first vibeview dev asks which platform to run and offers a build command detected from your project; it builds a debug build, uploads it, and opens the session in your browser. Later runs skip the questions. The details are in Quick start below.

How it works

Running vibeview dev starts a device session and connects it to a Metro bundler, so the app on the device is talking directly to your local JavaScript. Save a file and Fast Refresh updates the running app live, the same as it would on a simulator running on your own machine. You only need to rebuild and re-upload a debug build when you add or change a native dependency — everyday JavaScript and asset changes never require a new upload.

vibeview dev can drive the whole loop for you: it can run your build command, upload the result, start Metro if it isn’t already running, and open the session — or you can build and upload manually and just point dev at an existing app. Both paths are covered below.

Requirements

• The VibeView CLI, installed and logged in.
• A React Native project with a way to produce a DEBUG build: an iOS simulator .app build or an Android debug .apk. The build must match VibeView’s device architecture — x86_64 for Android, arm64 simulator slice for iOS — see Preparing your build: Architecture if your project filters ABIs (common for TV-targeted apps). An Android build without x86_64 native code runs only on devices that can run ARM code, and may crash at launch there; the session shows a warning when that happens.
• Metro (yarn start/npx expo start or equivalent) — vibeview dev can start this for you if you give it the command during setup.

Quick start

Run vibeview dev from your project root.

1. First run in a project: vibeview dev walks you through setup — which platform to run, an optional build command (a detected default is offered for Expo and bare React Native projects), and an optional command that starts Metro. Any of these can be skipped; skipped ones can be added to vibeview.json later (the command prints the exact keys to add). Your answers are saved to a vibeview.json file in the project so later runs start immediately with no prompts. The build command becomes the development profile; when you accept the detected one on iOS or Android, a preview profile that runs without Metro is saved next to it.
2. Getting an app to run: if you configured a build command and don’t have an uploaded app yet for this platform, vibeview dev builds and uploads one for you. If you already have an app, it asks whether to build a fresh one or reuse the existing upload. If you skipped the build prompt, it sends you to a picker over your already-uploaded apps.
3. The session: VibeView starts a device session — starting Metro first if it configured a command and nothing is running on the port yet — and opens the session in your browser. Edit your code and watch the change appear on the device. Press Ctrl-C in your terminal to end the session (this also stops a Metro that vibeview dev started for you). If vibeview dev goes away without that (the process is killed or crashes, or your computer goes to sleep), the session ends on its own within about 90 seconds, unless a browser tab is still watching it. A session that nobody uses also ends, after your organization’s idle timeout, even while vibeview dev keeps running. Saving a file (which reloads the app) and touching the device keep it going. About a minute before it would end, vibeview dev prints Session ends in 52 s: use the device or save a file to keep it (idle timeout: Settings > Session defaults).

Day to day, once setup is done, it’s one command:

vibeview dev

Choices are remembered per platform: vibeview dev --platform tvos switches to your TV app (asking which app once, the first time), and a bare vibeview dev reruns whatever platform you used last — no config editing to switch. One-off flags such as --metro-port, or switching away from the default platform in vibeview.json, are remembered for you alone in the git-ignored .vibeview/local.json, so the vibeview.json your team commits doesn’t change. The CLI keeps the .vibeview/ folder out of git with a .vibeview/.gitignore of its own (everything except test-spec.json), so your project needs no .gitignore entry.

After a native change, rebuild and upload before starting the session:

vibeview dev --build

For CI or a manual upload without starting a session, build and upload alone:

vibeview build

See CLI: dev and CLI: build for the full flag and config reference, including the vibeview.json schema.

If every device is busy

When no device of the requested kind is free, vibeview dev waits in the queue instead of failing: it prints your position and why you are waiting (all devices in use, or devices being updated), and the session starts as soon as a device is released. With --json, the queued event carries the same reason as queue_reason (devices_busy, devices_updating, plan_limit or link_limit, or null) and message. It waits up to 30 minutes; Ctrl-C gives up your place. The same applies to an agent starting a session through the MCP server’s dev_start.

Metro

If a previous vibeview build --cloud already created vibeview.json, vibeview dev may reuse that configuration without prompting for a Metro command. Start Metro in another terminal first (for example, npx expo start for Expo), then run vibeview dev --platform ios. Alternatively, add metroCommand to the relevant platform entry in vibeview.json so the CLI can start it on later sessions. A cloud build does not by itself configure a local Metro process.

If Metro is already running when you start a session, vibeview dev uses it as-is — it never touches a Metro it didn’t start. If nothing answers on the port and you configured a Metro command during setup, vibeview dev starts it (prefixing its output with [metro]) and stops it again when the session ends. If nothing is running and no Metro command is configured, the command stops with a clear message instead of opening a session your app can’t use. If Metro goes down mid-session, the terminal tells you too — start Metro in your project again, then reload the app in the session and it picks up right where you left off.

Building and uploading manually

If you’d rather run your own build tooling and skip the build-command prompts, that still works — upload a debug build with vibeview upload-app (see CLI: upload-app) and pick it from the picker on vibeview dev’s first run, or pass --app <id> directly:

vibeview upload-app ./build/MyApp.app
vibeview dev --platform ios --app <the-uploaded-app-id>

This is also the path for producing an iOS simulator build in CI — see Developing for iOS without a Mac below.

Debug builds

vibeview dev needs a debug build of your app — a build that can talk to a local Metro bundler. For Android that’s a debug .apk; for iOS it’s a simulator debug build. A release/production build won’t work with dev.

An Expo development build (a project with expo-dev-client) works the same way, on iOS and Android. The app opens straight from your Metro, every time it starts in the session: you don’t pick a development server on the build’s launcher screen, and the developer menu doesn’t open over your app at launch. It stays one tap away on the floating button.

When vibeview dev builds your app (--build, or the first run), it always uses the development build profile from vibeview.json. A preview profile, the same build in Release, is the one to build for share links, tests and collaborators, which open the app with no Metro.

TV apps

vibeview dev also runs TV apps: use --platform tvos (Apple TV simulator) or --platform androidtv (Android TV emulator). The same debug-build rules apply — an Android TV debug .apk, or a tvOS simulator debug build.

VibeView recognizes debug builds automatically when you upload them, and vibeview dev always runs the latest debug build of the app you pick — so if you also upload release builds of the same app, they don’t interfere with your dev loop. If the app you select has no debug build, vibeview dev stops with a clear message and does not start a session; upload a debug build with vibeview upload-app and run it again.

Roku works differently, because a channel has no JavaScript bundle to hot-reload: vibeview dev --platform roku streams the Roku with your channel installed and gives you a reload loop from the terminal instead of a Metro connection — press r to re-package, upload and restart the channel on the device (about five seconds), or pass --watch to reload on save. --detach works on Roku too, and vibeview dev-reload reloads the channel of a detached session (over MCP: dev_start with platform roku, then dev_reload), so an agent can run the whole loop without a terminal. A Roku dev session stays open for as long as the loop runs — in the terminal, detached, or held by the MCP server — even while nobody is sending commands to the device. The full loop is under Roku in the CLI reference.

If your build won’t install

If your debug build can’t be installed on the device (for example an Android build without an x86_64 architecture), vibeview dev stops the session and prints the install error instead of leaving you on an empty home screen. Rebuild with x86_64 included (reactNativeArchitectures=armeabi-v7a,arm64-v8a,x86_64 in android/gradle.properties) and upload the new build.

If the app you previously selected has been deleted, vibeview dev warns you and asks you to pick an app again. If you passed the deleted app’s id with --app, the command exits with an error telling you to run without --app to pick from the list.

If the app doesn’t load your JavaScript

If the app hasn’t asked Metro for its JavaScript 30 seconds after the session started, vibeview dev says so (with --json, a warning event; over MCP, on the next tool result). While Metro is still building an Expo development build’s first bundle for iOS, it waits up to three minutes before saying so. The device then usually shows a launcher, an error or a blank screen. Check that:

• the build is a debug build of this project (vibeview list-builds <app>; KIND must be debug), not a release build or a build of another app;
• Metro is running for this project, on the port vibeview dev uses (--metro-port, default 8081).

For an Expo development build (a project with expo-dev-client), vibeview dev also has Metro build your app’s JavaScript while the device starts, so the app opens sooner. If Metro can’t build it (a syntax error, a missing module), vibeview dev prints Metro’s error right away, since the device can’t always show it. Fix the error, then end the session and run vibeview dev again.

Developing for iOS without a Mac

The shortest route is a cloud build. Run vibeview build --cloud --platform ios once to compile the development profile on VibeView’s Macs, then start Metro and run vibeview dev --platform ios. After a native change, run the cloud build again instead of vibeview dev --build: --build runs your build command on your own computer, which needs Xcode. See Cloud Builds.

An iOS simulator debug build can also be produced in CI (for example with EAS Build or a GitHub Actions runner) and uploaded straight to VibeView, so day to day JavaScript work never requires owning a Mac:

name: Build iOS simulator debug build

on:
  workflow_dispatch:

jobs:
  build:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install VibeView CLI
        run: npm install -g vibeview

      - name: Install dependencies
        run: npm install

      # Build an iOS *simulator* debug build. With EAS Build:
      - name: Build iOS simulator debug build
        run: eas build --platform ios --profile development-simulator --local --output ./build/MyApp.tar.gz
      # With a bare React Native project, use a Debug-configuration
      # `xcodebuild` for the Simulator destination instead.

      - name: Upload debug build to VibeView
        env:
          VIBEVIEW_API_TOKEN: ${{ secrets.VIBEVIEW_API_TOKEN }}
        run: vibeview upload-app ./build/MyApp.tar.gz

Once the build lands on VibeView, run vibeview dev --platform ios from Windows or Linux — the CLI only needs your local Metro bundler, not a simulator or a Mac. When a native dependency changes, rebuild through the same CI workflow and upload the new debug build; the day-to-day loop of editing JavaScript and seeing it hot-reload never needs a Mac.

Limitations

• Only JavaScript and asset changes hot-reload. Adding or upgrading a native module requires rebuilding your debug build and uploading it again.
• Live Development supports React Native today. For other frameworks, contact support@vibeview.io.
• A live development session bills streaming minutes the same as any other VibeView session.