A CLI and a core library for Expo developers. DevHub keeps every Expo development build (dev client) on the machine, and installs a stored build on a running Android emulator or device, or on a booted iOS simulator.
Version: {{version}}. This file describes this version only.
Source: https://github.com/rootnative/devhub
devhub syncdownloads the EAS dev client builds of a project into the store, before EAS deletes them.devhub sync --alldoes this for each project thatdevhub syncsaw before.devhub listshows the stored builds.devhub wheregives the path of a build file.devhub deviceslists the Android emulators and devices, and on macOS the booted iOS simulators.devhub installinstalls a stored build on a device that runs now.devhub matchcalculates the native fingerprint of a project with the project's ownexpo/fingerprint, and shows the stored builds with the same EAS fingerprint.devhub uiserves a local page with the same functions, on 127.0.0.1.devhub whoamishows the EAS login state. A sync needs a login.devhub doctorchecks Node, the store, eas-cli and its login, adb, and Xcode, and gives the fix for each problem.@rootnative/devhub/cache-provideris an Expo build cache provider.npx expo run:androidandnpx expo run:iosthen store each new build, and install a stored build when the native code did not change.
NOT IMPLEMENTED, do not call: the import of a build file, the launch (boot a device, open the app), launch profiles, prune, and the desktop app. They are the plan only.
- Node 20.19 or later. Run
npx @rootnative/devhub <command>, or install the package globally to get thedevhubcommand. - For
devhub sync: eas-cli with a login (eas loginornpx eas-cli login). DevHub runseasfromPATH, ornpx --yes eas-cliwheneasis not onPATH. DevHub never reads, asks for, or stores a token. - For Android: adb from the Android SDK Platform-Tools. DevHub uses the
first
platform-tools/adbinANDROID_HOME,ANDROID_SDK_ROOT, or the default SDK folder of the system, and elseadbfromPATH. - For iOS: Xcode, on macOS only.
- Add
--jsonto each command. Then stdout holds one JSON value and nothing else. Progress and warnings go to stderr. - The exit code is
0for success,1for a failure, and2for a usage error. After a failure, stdout is empty and stderr holds the message, with these exceptions.devhub devices --jsonprints its JSON and exits with1when each device tool fails.devhub sync --jsonprints its JSON and exits with1when a project fails.devhub match --jsonprints its JSON and exits with1when no stored build matches.devhub whoami --jsonprints its JSON and exits with1when eas-cli has no login.devhub doctor --jsonprints its JSON and exits with1when a check has the statusfail. - When a command fails because a tool is missing, run
devhub doctor --json. Each check withwarnorfailhas afix. <id>is the EAS build ID, or a unique start of it.devhub list --jsongives each full ID.devhub installdoes not start a device, and does not open the app. Start the emulator or the simulator first. Then runnpx expo startin the project folder, and pressaori, to load the JavaScript.- When two or more devices of the build's platform are ready,
devhub installstops with exit code2. Give--device <id>with an ID fromdevhub devices --json. - DevHub never uninstalls an app. For a signing key conflict, it prints the
adb uninstallcommand and stops. An uninstall deletes the app data, so ask the user before you run that command. devhub installrefuses an Android App Bundle (.aab), an iOS device build (.ipa), and each iOS build on Windows or Linux.installProblemindevhub list --jsongives the reason and the fix before you try.devhub matchruns in the project folder, or in a folder inside it. It needs the dependencies of the project installed, and Expo SDK 52 or later. It runs noeascommand and no network call. A match is aListedBuild: give itsidtodevhub install.devhub uiruns until Ctrl+C. To read data, use the commands with--json, not the page.- Only one sync runs at a time. A second sync stops with exit code
1and a message that names the process of the first one. - A dev client is a debug build. Its JavaScript runs in development mode, so it does not show the speed of the app in production.
{{cli}}
{{json}}
devhub where <id> --jsonprints{ "id": string, "path": string }.devhub ui --jsonprints{ "url": string, "port": number }, and the server then runs until Ctrl+C.
Each path is absolute. Each date is an ISO 8601 string.
devhub list --json names the store folder in store. A build in
devhub list --json has source: "eas" for a build that devhub sync
downloaded, and "local" for a build that npx expo run:* made. An EAS
build has eas, the record of eas build:list --json without changes, so
it can have more fields than the type names. eas-cli drops each field with
a null value, so an absent field means "no value". A local build has
local in place of eas. The id of a local build is a UUID that DevHub
made, and devhub where and devhub install accept it the same as an EAS
build ID.
One folder holds the builds of all projects. It is never inside a project folder. Read it with the CLI. Do not write into it.
<DEVHUB_HOME>/
projects.json each project folder that devhub sync saw
sync.lock the process ID of the sync that runs now
builds/<id>/ the EAS build ID, or a UUID for a local build
build.json the record. A folder without it is incomplete.
<file> .apk, .aab, .tar.gz (iOS simulator), or .ipa
extracted/<id>/ the unpacked iOS simulator build, a cache
DEVHUB_HOME sets the folder. The default is
~/Library/Application Support/devhub on macOS, %LOCALAPPDATA%\devhub on
Windows, and $XDG_DATA_HOME/devhub or ~/.local/share/devhub on Linux.
Set it up in a project:
- Install
@rootnative/devhubas a dev dependency of the project. Expo CLI resolves the plugin from the project folder, not from a global install. - Add
"buildCacheProvider": { "plugin": "@rootnative/devhub/cache-provider" }toexpoin the app config. Expo SDK 53 reads it underexpo.experiments.
Rules:
- Expo CLI calls the provider only for
npx expo run:*, and on iOS only for a simulator.--binaryturns it off for one run. - A stored build serves a run only when the platform, the fingerprint, and
the variant (
--variant, defaultdebug;--configuration, defaultDebug) agree. On Android the APK must have native code for each ready device, or for the device that--devicenames, and for all four ABIs with--all-arch. On iOS a Mac with the sameprocess.archmade it. - Only builds that
npx expo run:*made serve a run. A build fromdevhub syncdoes not. - A run with
--scheme(iOS) does not use or store a build. - In a managed project (git ignores
android/andios/, so the fingerprint does not read them), the provider does not store a build when an app config file (app.json,app.config.json,app.config.*) is newer than the last prebuild (android/app/src/main/AndroidManifest.xml,ios/Podfile). Expo CLI runs prebuild only when the folder is missing, so that build can hold old native code. The fix: delete the folder, or runnpx expo prebuild --clean. - The provider never fails a run. It prints its lines with the prefix
› DevHub:, and Expo CLI builds the app when no stored build fits. devhub listshows a stored local build with the profilelocaland its variant.devhub matchshows it as a match.
import { listBuilds } from '@rootnative/devhub'. The package is ESM only,
for Node. The types are in dist/index.d.ts. The API can change in each
version before 1.0.0.
{{exports}}