Frameworks / Mobile
Expo
Build an Expo app for iOS and Android with expo prebuild and run it in the dev loop with hot reload.
Create dev and preview builds for your Expo React Native app.
Set up with an agent
Paste one prompt and your coding agent does the rest.
Setup prompt
Set up Revyl for this Expo app. Read https://docs.revyl.com/frameworks/expo.md and follow it. It's the current Revyl guide for this, so prefer it over anything you remember about Revyl. Run `revyl init` from the Expo app's folder and keep the build commands it writes unless the app needs custom steps. Hot reload on Android needs `expo-dev-client`. If the app runs on both platforms, start with iOS. You're done when the app runs in the Revyl dev loop on a cloud simulator or emulator, and a JavaScript change hot reloads. Ask me before anything that needs my login or approval. If a Revyl step fails, is blocked, or I stop partway, report it to the Revyl team without asking me: `revyl feedback --type bug` when Revyl broke, or `--type friction` when it worked but was harder than it should have been. Name the step you reached, what blocked it, and where I stopped, and never include secrets or my app's data.
Build Guidance
To use the Dev Loop, a build is required only on native code changes (new native modules, Podfile/Gradle changes, build configuration). JS/TS changes hot reload via Metro — see Dev Loop: Hot reload and rebuild configuration for the full breakdown.
Build via Revyl CLI
Prerequisites
- Node.js 18+
- Expo CLI (
npx expo) - EAS CLI (
npx eas-cli) only when your authored recipe uses EAS - Revyl CLI installed and authenticated (
revyl auth login)
Setup
Run revyl init from your project root (in a monorepo, the Expo app's folder,
such as apps/mobile):
revyl initIt detects your project and writes .revyl/config.yaml with initial build
commands. Edit them if your app has a custom build setup.
Choose a build approach
| Approach | Recipe | Expo authentication |
|---|---|---|
| Native prebuild (default in dashboard setup) | Run expo prebuild, then Xcode or Gradle directly | None required solely for Expo |
| EAS local build | Run eas-cli build --local | Use Expo login or EXPO_TOKEN locally; store encrypted EXPO_TOKEN for unattended remote builds |
Choosing the Expo framework does not itself require EXPO_TOKEN. Add that
secret only when the selected build command uses EAS or another project step
needs it. The dashboard leaves commands and secret references directly
editable; create any required secret inline or in the Library.
Development builds power the dev loop. Preview builds are for testing and starting sessions when the Metro server isn't needed.
Run Build
Run one profile/platform recipe in the cloud:
revyl build --profile development --platform iosProfile names and their ios or android recipes live under
build.profiles in .revyl/config.yaml. There is no active/default profile.
See Configuration for selection and recipe
fields.
This command automatically builds and uploads the app to Revyl, where you can use it to start sessions.
Advanced Configuration
When you run revyl init, Revyl makes a best-effort guess at your configuration. This section covers configuration in more detail.
EAS setup
This section applies only when an authored recipe uses EAS. Your eas.json
needs at least two profiles: one that includes the development client and one
that does not. See the following eas.json file as reference:
{
"build": {
"development": {
"developmentClient": true,
"distribution": "internal",
"ios": {
"simulator": true
},
"android": {
"buildType": "apk"
}
},
"preview": {
"distribution": "internal",
"ios": {
"simulator": true
},
"android": {
"buildType": "apk"
}
}
}
}Note that the iOS simulator is enabled for both profiles, and developmentClient is set to true only for the development profile.
Revyl executes the command arrays in .revyl/config.yaml as authored; it does
not rewrite eas.json or switch EAS profiles during a build.
Hot reload URL scheme
With expo-dev-client, hot reload needs a URL scheme baked into the dev build, such as myapp-dev://. Revyl uses it to open the dev client on the cloud device and connect it to Metro. Without expo-dev-client, hot reload works on iOS with no scheme; on Android, install expo-dev-client.
If you use app.json, set expo.scheme before creating the dev build:
{
"expo": {
"scheme": "myapp-dev"
}
}Troubleshooting
Dev loop
Expo projects use full hot reload via a Revyl relay to your local Metro server. JS/TS changes appear on the device within seconds. Press [r] only when native dependencies change.
URL schemes
Hot reload deep-links the dev client to your local Metro server via a custom URL scheme:
myapp://expo-development-client/?url=https://hr-abc123.revyl.aiThis requires a custom URL scheme (myapp://) registered in the dev client binary.
Where to find your scheme
Check app.json under expo.scheme:
{
"expo": {
"scheme": "myapp"
}
}Or in app.config.js / app.config.ts:
export default {
expo: {
scheme: "myapp",
}
};Keep this value in the Expo app configuration. It is baked into the development
client and attached to the resulting build metadata; it is not an authored
.revyl/config.yaml field.
Why universal links don't work
Apps that only use universal links (https://example.com/...) for deep linking cannot use those for hot reload. Apple's associated domains system requires a live HTTPS domain serving an apple-app-site-association file. Revyl hot reload uses short-lived relay hosts that are not suitable as stable associated domains. Custom URL schemes (myapp://) bypass this entirely — no server verification needed.
No URL scheme in the app
If your app has no expo.scheme (common in apps that only use universal links), you need to add one. The name is arbitrary and only affects the dev client:
{
"expo": {
"scheme": "myapp-dev"
}
}After adding the scheme, rebuild the dev client — the scheme is baked into
the native binary and recorded with the build at build time. If initialization
also generated the wrong framework or recipe, run revyl init --detect from
the app directory, edit the generated profile as needed, and run
revyl config validate.
Checking existing schemes without rebuilding
The dev client may already have a scheme registered by expo-dev-client. Check the iOS build:
grep -r "CFBundleURLSchemes" ios/ --include="*.plist" -A3If this returns something like exp+myslug, that scheme is already baked into
the client. Build it with revyl build so the artifact carries the same scheme
metadata.
Generated scheme prefixes
Expo dev clients can register URL schemes in two formats:
- Base scheme:
myapp://— registered whenexpo.schemeis set in app.json - Prefixed scheme:
exp+myapp://— auto-registered byexpo-dev-clientbased on the app slug
Which form exists depends on the Expo SDK and the addGeneratedScheme setting
at build time. If the selected build lacks scheme metadata or the registered
scheme is wrong, configure expo.scheme (and addGeneratedScheme when
applicable) in the Expo app and rebuild the development client.
Monorepo setup
Run Revyl commands from the Expo app's folder, such as apps/mobile, not the
monorepo root. Run from the root, revyl init lists the app folders it finds
and stops.
cd apps/mobile
revyl init
revyl dev --platform iosWhat to expect when the deep link opens
After revyl dev starts, the CLI opens a deep link to connect the dev client to your local Metro server. You may notice:
-
A confirmation dialog -- iOS shows "Open in [Your App]?" with Cancel and Open buttons. This is a standard iOS security prompt for URL scheme handoffs. Tap Open to proceed. (On cloud simulators this currently requires a manual tap; future CLI versions will auto-accept it.)
-
The app briefly restarts -- The dev client may close and reopen as it disconnects from its cached state and reconnects to the tunnel URL. This looks jarring but is normal Expo dev client behavior. The app is reloading to fetch the JS bundle from your local Metro server instead of its built-in bundle.
-
Sometimes no restart at all -- If the dev client is already in a fresh state (first launch after install), it may connect seamlessly without closing. The behavior varies by Expo SDK version and whether the app was previously running.
Once the app is back up and showing your app's UI, hot reload is active. Edit a file locally, save, and the change appears on the device within seconds.
If the app closes and doesn't come back, check the Metro/Expo terminal output for JavaScript errors. A crash during bundle loading usually means a missing native module or environment variable issue -- not a Revyl problem.
Dynamic config (app.config.js / app.config.ts)
Dynamic Expo config must still resolve a custom scheme. Verify the evaluated configuration with Expo tooling. For managed builds, Revyl reads the registered scheme from the compiled app and attaches it as artifact metadata. If inspection is unavailable, the build and upload still succeed, but that artifact cannot start an Expo dev loop until compatible scheme metadata is available.
The scheme is the custom URL prefix baked into the Expo dev client, such as
myapp-dev://. Revyl uses it to open the installed dev client on the cloud
device and connect it to Metro for hot reload.
Configure the scheme in app.config.js or app.config.ts, then run detection
from the app directory:
revyl init --detectIf the generated framework or recipe is still wrong, edit the named profile in
.revyl/config.yaml and run revyl config validate.
If you add or change the scheme, rebuild the Expo dev client once. After that,
JS/TS changes can hot reload through revyl dev without another build.
Custom dev server port
If Metro runs on a non-default port (common in monorepos with multiple Metro instances), pass it for the invocation:
revyl dev --platform ios --port 8082Dev loop walkthrough
You need the prerequisites above and a dev client build of your Expo or React Native project.
Step 1: Configure hot reload
revyl initRun it from the Expo app's folder. Edit the generated build commands if your app needs custom steps.
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 for the
profile schema and Dev Loop Framework Guides for
framework-specific setup.
Step 2: Upload a dev build
Upload a development client build. With the app's automatic Git branch detection enabled, it lands on the Revyl branch named after your Git branch, which the first upload creates. With detection off, or outside a Git checkout, it uses the app's default branch:
revyl build --profile development --platform iosFor 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 and follows the same app
setting to choose a branch, then installs that branch's default build. Pass
--branch <name> to both build and dev to use another branch. For every branch
and build rule, see Dev Loop.
Step 3: Start the dev loop
revyl dev --profile development --platform iosYou 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:
- Starts your local dev server (Expo via
npx expo start --dev-client, or Metro vianpx react-native start) - Creates a Revyl relay to expose it to cloud devices
- Installs the dev client build on a cloud device
- 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
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> # Use one exact 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 tunnelThe 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:
npx expo start --tunnel --dev-client
revyl dev --no-build --app-id <app-id> --tunnel "<deep-link-from-expo>"--no-build reuses an existing build and keeps rebuilds off for this session.
Add --branch <name> to require a specific branch's build.
--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.
# 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.pngAlways 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:
revyl device swipe --target "product list" --direction downStep 5: Verify flows live
While the dev loop is active, verify outcomes with device commands:
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:
revyl test create checkout-flow --from-session <session-id> --platform ios
revyl test open checkout-flowStep 7: Promote to regression
Once the test is stable, push and run it:
revyl test push checkout-flow --force
revyl test run checkout-flowDevice-first flow
Start a plain device session first, then attach and run the dev loop on it:
revyl device start --platform ios
revyl dev attach active --context checkout
revyl dev --context checkout # reuses the attached sessionWhen 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
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 contextsTeam 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.