> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revyl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Expo Dev Loop Guide

> Set up revyl dev for fast local verification with hot reload on cloud devices

## Prerequisites

* Revyl CLI installed and authenticated (`revyl auth login`)
* An Expo or React Native project with a dev client build

## Step 1: Configure hot reload

```bash theme={null}
revyl init
```

Initialization detects the framework and writes named build profiles. In a
monorepo, run `revyl init --detect` from the Expo app directory. If detection
still needs correction, edit `build.framework` and the generated development
profile, then run `revyl config validate`.

Configure the custom URL scheme in the Expo app before building the development
client; the scheme is attached to the build artifact rather than authored in
`.revyl/config.yaml`. See [Configuration Files](/cli/configuration) for the
profile schema and [Dev Loop Framework Guides](/develop/frameworks/xcode) for
framework-specific setup.

## Step 2: Upload a dev build

Upload a development client build for the branch you're working on:

```bash theme={null}
revyl build --profile development --platform ios
```

For Expo, this is a dev client build. For bare React Native, it's your debug build.

`revyl build` runs in the cloud.
The dev loop remains local unless you use `revyl dev --remote`.

`revyl dev` resolves one named profile/platform recipe, then picks the build in
that recipe's app that matches your current git branch. If no match is found,
it falls back to the latest available build in the same app.

## Step 3: Start the dev loop

```bash theme={null}
revyl dev --profile development --platform ios
```

You may omit the flags when the result is deterministic. `revyl dev` first
prefers one unique development-like profile and then accepts only a sole
eligible profile or platform. It prompts for remaining choices interactively
and fails with the valid choices non-interactively. This is invocation-time
selection, not an active/default profile.

This:

1. Starts your local dev server (Expo via `npx expo start --dev-client`, or Metro via `npx react-native start`)
2. Creates a Revyl relay to expose it to cloud devices
3. Installs the dev client build on a cloud device
4. Opens the device session in your browser

Normal runs keep advisory HMR diagnostics quiet so they do not look like startup
failures. If you are troubleshooting relay or HMR internals, run with
`revyl dev --debug` to print the diagnostic probes.

Now edit code locally and see changes reflected on the device instantly.

### Platform and build overrides

```bash theme={null}
revyl dev --profile development --platform android  # Explicit recipe
revyl dev --no-open                       # Don't open browser (headless/SSH)
revyl dev --profile development --platform ios --build  # Fresh local build
revyl dev --profile development --platform ios --remote # Remote build
revyl dev --build-version-id <id>         # Pin a specific build
revyl dev --context ios-main              # Named context for parallel loops
revyl dev --force-hot-reload              # Diagnostic launch after Expo relay transport
revyl dev --no-build --tunnel "<expo-dev-client-link>"  # Reuse an Expo tunnel
```

The selected recipe remains fixed for the dev context. Forced builds, remote
builds, and later `revyl dev rebuild` operations all use that same recipe.

If Revyl starts Expo and verifies relay transport but times out proving the
first Expo manifest, retry with `--force-hot-reload` first. This launches after
the relay and dev server start, skipping only the manifest and bundle proof. If
the app loads, keep working; if the dev client shows a project load error,
restart Expo/Metro or capture `revyl device report --session-id <id> --json`.

If you already run Expo with its own tunnel, you can collapse the manual device
start + deep-link step into one command:

```bash theme={null}
npx expo start --tunnel --dev-client
revyl dev --no-build --app-id <app-id> --tunnel "<deep-link-from-expo>"
```

`--tunnel` accepts either the full Expo dev-client link or the raw `https://...`
tunnel URL. Passing the full dev-client link does not depend on an authored
scheme field in the local Revyl config. Prefer the Revyl relay first in
cloud-agent environments; use Expo tunnel fallback only after device screenshots
or `revyl device report --session-id <id> --json` show force mode still did not
load through the relay.

## Step 4: Interact with the device

Use `revyl device` commands to observe, act, and verify in a tight loop.

```bash theme={null}
# Observe
revyl device screenshot --out before.png

# Act
revyl device tap --target "Sign In button"
revyl device type --target "email field" --text "user@example.com"
revyl device type --target "password field" --text "secret123"
revyl device tap --target "Log In"

# Verify
revyl device screenshot --out after.png
```

Always follow the **observe-act-verify** pattern: screenshot before an action, take the action, then screenshot again to confirm the result.

Scroll through content with swipe:

```bash theme={null}
revyl device swipe --target "product list" --direction down
```

## Step 5: Verify flows live

While the dev loop is active, verify outcomes with device commands:

```bash theme={null}
revyl device validation -s 0 "Home screen shows the signed-in user"
```

## Step 6: Create tests from the session

After verifying a flow manually, convert the device session into a regression test:

```bash theme={null}
revyl test create checkout-flow --from-session <session-id> --platform ios
revyl test open checkout-flow
```

## Step 7: Promote to regression

Once the test is stable, push and run it:

```bash theme={null}
revyl test push checkout-flow --force
revyl test run checkout-flow
```

***

## New branch workflow

When you create a new branch and want `revyl dev` to use that branch's build:

```bash theme={null}
git checkout -b feature/new-login
revyl build --profile development --platform ios  # Tagged with your branch
revyl dev --profile development --platform ios    # Uses the same recipe
```

## Device-first flow

Start a plain device session first, then attach and run the dev loop on it:

```bash theme={null}
revyl device start --platform ios
revyl dev attach active --context checkout
revyl dev --context checkout            # reuses the attached session
```

When the dev loop exits, the attached session stays running. Run `revyl dev --context checkout` again to resume, or `revyl dev stop` to detach.

## Context management

```bash theme={null}
revyl dev list                         # List dev contexts in the current worktree
revyl dev use ios-main                 # Switch the current context
revyl dev status                       # Show context status (JSON)
revyl dev rebuild                      # Trigger a rebuild
revyl dev stop                         # Stop the current context
revyl dev stop --all                   # Stop all contexts
```

## Team sharing

All developers push builds to a shared app container (the `app_id` in config). Each developer gets their own cloud device session, relay URL, and local server. For JS projects, multiple developers can share the same dev build and still see their own code changes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.