Skip to main content
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. For build and upload steps, see Expo Build Guide.

​
How detection works

The CLI looks for two things in the current directory:
  1. "expo" in package.json dependencies or devDependencies
  2. At least one project indicator: app.json, app.config.js, app.config.ts, eas.json, or .expo/ directory
If both are present, the Expo provider matches at confidence 0.9 — the highest of any provider. This means Expo wins over Swift (0.7) and Android (0.6) when all three detect the same directory. If either condition fails (common in monorepos), the Expo provider returns nil and lower-confidence providers may match instead. See the monorepo section below.

​
URL schemes

Hot reload deep-links the dev client to your local Metro server via a custom URL scheme:
This requires a custom URL scheme (myapp://) registered in the dev client binary.

​
Where to find your scheme

Check app.json under expo.scheme:
Or in app.config.js / app.config.ts:
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. 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:
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:
If 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 when expo.scheme is set in app.json
  • Prefixed scheme: exp+myapp:// — auto-registered by expo-dev-client based 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

In monorepos (Turborepo, Nx, pnpm workspaces), the Expo app typically lives in a subdirectory like apps/native/, apps/mobile/, or packages/app/.

​
Run from the Expo app directory

All Revyl commands must run from the directory containing the Expo app’s package.json — not the monorepo root.
The CLI resolves the working directory by calling FindRepoRoot, which walks up from the current directory looking for .revyl/. If the monorepo root also has a .revyl/ directory (common for CI test configs), make sure you’re in the correct subdirectory.

​
Why detection fails in monorepos

Two things go wrong:
  1. Hoisted dependencies — Package managers like pnpm, Yarn, and npm may hoist expo to the root node_modules/ or use workspace:* protocol in the local package.json. The Expo provider reads the local package.json and checks for "expo" in dependencies or devDependencies. If it’s not there, the provider returns nil (no match).
  2. Native directories match other providers — Every Expo project with prebuild has ios/ containing .xcodeproj files (triggering the Swift provider at confidence 0.7) and android/ containing build.gradle (triggering the Android provider at confidence 0.6). When the Expo provider returns nil, these become the top matches.
The result: revyl init detects “Swift/iOS (coming soon)” and “Android (coming soon)” instead of Expo. Fix: Rerun detection from the Expo app directory:
If detection remains ambiguous, edit build.framework and the generated profile recipes in .revyl/config.yaml, then run revyl config validate. If expo is genuinely missing from the local package.json, add it:
The generated .revyl/config.yaml should have build.framework: expo and a named development profile with the applicable iOS and/or Android recipes. The custom URL scheme remains in the Expo app configuration, not the Revyl YAML. After revyl dev starts, the CLI opens a deep link to connect the dev client to your local Metro server. You may notice:
  1. 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.)
  2. 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.
  3. 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:
If 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: