Build, sign and install Expo and bare React Native iOS dev builds from Linux, with no Mac, then develop with Metro and Fast Refresh over Wi‑Fi. Built on xtool and the official React Native / Expo SwiftPM pipeline.
Status: alpha, react-native-xtool@0.1.0-alpha.8 on npm under the
alpha tag. Verified end to end on a physical iPhone on 2026-11-04 and 2026-11-05: the first launch without Reload,
the dev client and the app icon; bare React Native 0.85; react-native-vision-camera, react-native-video,
react-native-device-info and @react-native-community/netinfo, with react-native-app-auth linked and an entitlements
file; and ML Kit text recognition with react-native-svg's Metal filters. On 2026-11-06 a production bare React Native
0.85.0 app with an Objective-C app target and 20 native libraries built, installed and launched on a physical iPhone.
Demo video coming soon.
| Project or target | Status |
|---|---|
| Expo SDK 58 (expo 58.0.21 or newer 58.x, react-native 0.88.1) | ✅ details |
| Expo SDK 57 (expo 57.0.31 or newer 57.x, react-native 0.86.3) | ✅ details |
Bare React Native 0.88.x from 0.88.0 (@react-native-community/cli init) |
✅ details |
| Bare React Native 0.85.x from 0.85.0, 0.86.x from 0.86.2, 0.87.x from 0.87.1 (0.85.3 and 0.86.2 build-verified only) | ✅ details |
| Bare React Native + Expo modules (hybrid), React Native 0.88.1 | ✅ details |
| Expo SDK 54–56, React Native 0.84 and older, 0.86.0, 0.86.1, 0.87.0 | ⏳ not yet (Expo SDK 53 and older are refused as well) |
| iOS simulator | ❌ macOS only |
| Production / App Store builds | ❌ use EAS |
| macOS or Windows as the host | ❌ (WSL2 on x86_64 should work as Linux; not tested yet, reports welcome) |
Bare React Native versions: 0.85.x from 0.85.0, 0.86.x from 0.86.2, 0.87.x from 0.87.1 and 0.88.x from 0.88.0 (0.88.1, 0.88.0, 0.87.1, 0.86.3 and 0.85.0 are verified on a device; 0.85.3 and 0.86.2 only build, they have not been run on a device), see Supported React Native versions. A newer patch of one of these lines builds with a warning naming the verified versions. An older version, a prerelease or another minor stops with one error naming these floors. Expo SDK 57 and 58 work the same way: newer patches of the SDK's packages build with a warning, older ones stop, and react-native stays exact (0.86.3 on SDK 57, 0.88.1 on SDK 58) (details).
Apps that grew from older React Native templates build too: a production bare React Native 0.85.0 app with an
Objective-C app target (main.m, AppDelegate.h and AppDelegate.mm next to the project, a bridging header and a
Swift file) and 20 native libraries builds, installs over USB and launches on a physical iPhone (checked on
2026-11-06; its features are not checked yet, details).
rn-xtool doctor --project shows which line your project is on and what rn-xtool finds in it (the SwiftPM scripts
and prebuilt artifacts it would use, Expo's plugin and modules, podspec features, the app's own includes), without
the toolchain, login and device checks (details).
CocoaPods is not needed: the Podfile is ignored. Any library with a podspec is tried automatically (CocoaPods-only
ones get a generated Package.swift, and the pods they depend on come from SwiftPM packages or, for pods of prebuilt
binaries, from the CocoaPods CDN); docs/libraries.md lists the ones verified on a device and what
does not work yet (a library's own vendored binaries, Xcode-only tools).
- Linux x86_64 (arm64 should work, untested). Node 22.12+. About 25 GB of free disk for setup and the first build (Swift toolchain, Darwin SDK, React Native artifacts), plus the Xcode.xip.
Xcode.xip(Xcode 27.x, about 12 GB), downloaded yourself from developer.apple.com with an Apple ID.- An Apple ID. Free accounts: signatures last 7 days, 3 apps at a time, no push notifications or special entitlements (a paid developer account lifts these).
- An iPhone connected over USB for the first install (later installs can go over Wi‑Fi).
- FUSE 2 for the xtool AppImage (
sudo apt install libfuse2t64on Ubuntu 24.04 and newer,sudo apt install libfuse2on older releases),python3,iproute2.setupinstalls Swift and prints the exactapt-getline for any missing Swift system packages (list). - Ruby 2.7+ (
sudo apt install ruby), which reads podspecs as CocoaPods does. Without it, rn-xtool reads them with a reduced reader that evaluates a subset of Ruby, andrn-spmsays so in a⚠line (details). - npm or Yarn classic. patch-package needs a flat
node_modules; pnpm and Yarn PnP are not supported, andbuildstops on them early (details).
npm i -g react-native-xtool@alpha # the package is react-native-xtool, the command is rn-xtool
npx react-native-xtool@alpha doctor # or try it without installing
npm i -g github:WillyAntunez/react-native-xtool # from GitHub (builds on install via `prepare`)
git clone https://github.com/WillyAntunez/react-native-xtool # from a clone, for contributors
cd react-native-xtool && npm ci && npm run build && npm linkUpdating: re-run npm i -g react-native-xtool@alpha (or use npx react-native-xtool@alpha).
rn-xtool setup --xcode-xip ~/Downloads/Xcode_27.1.xip # once per machine: Swift 6.4, xtool 1.24.0, Darwin SDK
rn-xtool auth login # your Apple ID (interactive, handled by xtool)npx create-expo-app@latest my-app --template default@sdk-58 && cd my-app
rn-xtool run # with the iPhone plugged innpx @react-native-community/cli init MyApp --version 0.88.1 && cd MyApp
rn-xtool run # with the iPhone plugged inrun = build + install + start, skipping build and install when nothing changed. A fresh create-expo-app
project works as is: with no ios.bundleIdentifier in app.json, build writes com.anonymous.<slug> there and tells
you (change it if you want another; expo prebuild would ask you for one). First run on the iPhone
(checklist):
- Enable Developer Mode (Settings > Privacy & Security > Developer Mode); the phone reboots.
- Trust your Apple ID under Settings > General > VPN & Device Management.
- Open the app by hand and allow Local Network access; keep the phone on the same Wi‑Fi as the computer.
rn-xtool run is the one command to use. It fingerprints your installed dependencies (plus patches/*.patch and
rn-xtool's own version) and compares them with the last successful build and install (details):
- Up to date, and the baked Metro port and LAN IP still work: prints
Native app is up to date, skips build and install, and starts Metro without clearing its cache. - Changed (for example after
npx expo install <native lib>), never installed, or the port or LAN IP changed: it rebuilds, reinstalls and starts Metro with--clear. Any dependency change rebuilds, native or JS. run --force(or--clean) always rebuilds and reinstalls;start --clearforces a Metro cache reset.run --networkinstalls over Wi‑Fi, no cable, after a one-time USB pairing (docs/wifi-install.md).
Some libraries depend on CocoaPods pods that ship prebuilt static binaries instead of sources, such as Google's ML Kit behind @react-native-ml-kit/text-recognition. rn-xtool reads their specs from the CocoaPods CDN, downloads the files on your machine, wraps them for SwiftPM and links them, with no CocoaPods. ML Kit text recognition 2.0.0 builds this way on bare React Native 0.88.1, and recognizes text on a physical iPhone (checked on 2026-11-05).
- Before the first download,
buildnames the files, their sizes, the host and the vendor, with the vendor's terms:ℹ pods — @react-native-ml-kit/text-recognition needs 10 CocoaPods binaries that are not in rn-xtool's cache, 40.3 MB from dl.google.com: … From Google, Inc. (…; terms: https://developers.google.com/ml-kit/terms). …. The files are Google's, under the ML Kit Terms; rn-xtool downloads them for your own build and does not accept the terms for you. - It records each file's sha256 in
rn-xtool-pods.lock.jsonat the project root: commit it, so other machines check that they get the same files. The files are kept in~/.cache/rn-xtool/pods; the copies a build puts in the app's folders are git-ignored, and none reachespatches/. - Disk: before the first download,
buildchecks for about 8 times the download size. For ML Kit's 40.3 MB, the cache then holds about 237 MB and each app about 66 MB of copies; the app grows by about 53 MB. - With the lock and a full cache, the
podsstep makes no request, so a rebuild works without internet (withios-xtool/.buildkept; with no network at all, setlanIpinrn-xtool.config.json)."exclude"inrn-xtool.config.jsonstill builds the app without the library.
Details, every message and what to do: docs/troubleshooting.md.
| Command | What it does |
|---|---|
setup [--xcode-xip <path>] [--wifi [--yes] [--udid <udid>]] |
Installs Swift via swiftly, the xtool AppImage and the Darwin SDK. Idempotent. --wifi is the one-time USB step for Wi‑Fi installs: it caches the pair record and, with --yes, enables Wi‑Fi connections on the iPhone. |
auth [args...] |
Runs xtool auth <args> (auth login, auth logout); with no arguments, xtool auth status. |
doctor [--project] [--report] |
Checks toolchain, SDK, login, connected device, Wi‑Fi install readiness and project. Exits non-zero on problems. --project checks only the project in the current folder: its version gates, what rn-xtool finds in it and the setups it cannot build yet. --report prints the same checks as one block to paste into a GitHub issue, with your home folder, Apple ID, Team ID, bundle identifiers, UDIDs, device names, IP and MAC addresses replaced by placeholders, and makes no network request (details). |
build [--clean] [--skip-precheck] |
Prebuild if ios/ is missing (Expo only), patches, RN/Expo SwiftPM pipeline, ExpoModulesJSI (Expo modules only), generates ios-xtool/, checks the app's own sources (precheck), xtool dev build. --clean re-runs expo prebuild --clean for Expo; for bare it removes ios/build and ios-xtool and leaves the rest of ios/ alone. --skip-precheck leaves the precheck step out, and the check of the app's own includes at build start warns instead of stopping (details). |
install [--network [ip] [--udid <udid>] [--pair-record <file>]] |
Signs and installs the app on the USB-connected iPhone (over Wi‑Fi without the cable with --network, see docs/wifi-install.md), then prints, for apps with expo-dev-client, the Metro URL with a link and QR code that open the app on it, and the first-run checklist. |
start [--clear] |
Starts Metro (npx expo start; npx react-native start for bare) on the port and LAN IP the app was built for. Tells you to rebuild if either changed; clears the Metro cache when dependencies changed (or with --clear). With expo-dev-client it announces Metro to the dev launcher under the installed app's bundle id. |
run [--clean] [--force] [--network [ip]] [--skip-precheck] |
build and install when dependencies changed (or with --force), then start. --network installs over Wi‑Fi; --skip-precheck goes to build. |
Optional rn-xtool.config.json in the project root (recommended). A rn-xtool.config.js also works, but it must be
CommonJS (module.exports = {...}) unless your project is ESM. Both are merged, .js winning:
{ "xcodeXipPath": "/home/me/Downloads/Xcode_27.1.xip", "metroPort": 8082, "lanIp": "192.168.1.20",
"rnArtifactsDir": "/home/me/rn-artifacts/0.88.1/debug", "xtoolPath": "/opt/xtool/xtool" }| Key | Default | Meaning |
|---|---|---|
xcodeXipPath |
none | Xcode.xip used by setup when --xcode-xip is not given (the flag wins). |
metroPort |
8081 |
Metro port, baked into the app at build time. |
lanIp |
auto-detected | LAN IP the phone uses to reach Metro, baked into the app. Pin it when a VPN is on. |
rnArtifactsDir |
none | Use already-downloaded React Native prebuilts instead of downloading (offline). |
xtoolPath |
managed copy | Use a specific xtool binary in setup, doctor and install (setup skips the download; it must exist and be executable). |
projectKind |
auto-detected | "expo" or "bare", to skip project detection. |
knownLimits |
none | { "allow": [...] }: build anyway a setup rn-xtool refuses early. List a package name, or "pnpm", "pnp" or "hoisted"; the refusal becomes a warning, and the build may fail later (details). |
pods |
rn-xtool's table | { "<pod>": { "url", "exact", "products" } }: the SwiftPM package for a CocoaPods pod a library depends on, merged over rn-xtool's own entries (AppAuth, SwiftUIIntrospect, the source pods ML Kit needs) field by field (details). |
exclude |
none | ["<package>"]: native modules left out of rn-xtool's iOS builds, without touching react-native.config.js (details). |
Entitlements. build reads the file CODE_SIGN_ENTITLEMENTS names in the app target's Debug configuration (on
Expo, in the Xcode project expo prebuild writes) and passes it to xtool when the file has keys. Before compiling it
prints a ⚠ line for each key a free team does not get, such as push notifications or Wi‑Fi information
(details).
- The Metro port and LAN IP are baked into the app: if either changes, rebuild and reinstall (
rundoes it for you). - The installed bundle ID is
XTL-<TEAM_ID>.<bundleIdentifier>because xtool renames it. expo-dev-client: the launcher's and dev menu's icons are missing (noactoolon Linux); the app opens Metro by itself from its second launch, and the link and QR code frominstallcover the first one (details).- The app icon comes from the
AppIconset as one PNG; dark, tinted and Icon Composer icons and custom splash screens are not supported (no asset catalog compiler on Linux; details). - Bare projects: one app target and one
.xcodeproj, always built for iOS 16.4;.xcconfigfiles, capabilities, script phases, storyboards, asset catalogs (except the app icon) and.xibfiles are not used; entitlements come from the DebugCODE_SIGN_ENTITLEMENTSfile (details). - Metal shaders are not compiled on Linux. react-native-svg's filters use the prebuilt
*.metallibfiles it ships, which reach the app inRNSVGFilters.bundle(checked on a physical iPhone on 2026-11-05). doctor --projectandbuildrefuse early, with the reason and a link, the setups rn-xtool knows it cannot build yet: CocoaPods-only libraries with prebuilt binaries of their own (async-storage 3.x) or that depend on a CocoaPods pod from a git source without a known SwiftPM package, Expo modules that build vendored C sources (expo-sqlite), pnpm and Yarn PnP installs, and react-native or expo hoisted to a parent folder.knownLimits.allowinrn-xtool.config.jsonbuilds them anyway. Other unsupported setups still fail during the build (details).- A daily drift watch checks the newest patch of each supported line (version gates, bundled patches, portable library manifests) and opens an issue in this repo when one breaks. It does not compile or run the app, so a patch release it reports green can still fail G4 or the build (details).
- docs/how-it-works.md: what
setupinstalls, the patches, the build steps, reference timings. - docs/bare-react-native.md: bare React Native and hybrid projects in detail.
- docs/wifi-install.md: installing over Wi‑Fi, WSL2, Wi‑Fi troubleshooting.
- docs/troubleshooting.md: first-run checklist and common problems.
- docs/libraries.md: library compatibility matrix.
- docs/recipe.md: the technical recipe the CLI automates, with file locations.
- docs/RELEASING.md: how releases are made.
- docs/README.md: index of every page, including upstream write-ups, research and design records.
Branches: feature/<kebab-name> or fix/<kebab-name>; Conventional Commits in English (type: short imperative summary). Run npm test before opening a PR; CI runs it, with lint and the private-names scan, on every pull request
to main and every push to main. Tests read the patched upstream React Native and Expo files from pinned npm
tarballs: run node scripts/fetch-test-tarballs.mjs once to fetch them into tests/.cache (each is checked against its
pinned checksum). A failed fetch is retried once and then stops with the error. Without the tarballs, the tests that
read them skip and their titles give the command; a cached tarball whose checksum does not match fails them. Tests that
need a reference app or a device say so in their titles and skip; CI lists them by name in the run summary.
To report a problem, run rn-xtool doctor --report and open an issue with one of the templates
(details).
MIT, see LICENSE. You bring your own Xcode.xip and Apple ID: rn-xtool redistributes nothing from Apple;
it extracts the SDK locally from your copy, and Apple's Xcode license terms apply to that use.