Skip to content

About

Build Expo and bare React Native iOS dev builds on Linux and install them on a real iPhone, no Mac needed

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

react-native-xtool

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.

npm license

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.

Which projects work

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).

Before you start

  • 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 libfuse2t64 on Ubuntu 24.04 and newer, sudo apt install libfuse2 on older releases), python3, iproute2. setup installs Swift and prints the exact apt-get line 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, and rn-spm says so in a ⚠ line (details).
  • npm or Yarn classic. patch-package needs a flat node_modules; pnpm and Yarn PnP are not supported, and build stops on them early (details).

Install

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 link

Updating: re-run npm i -g react-native-xtool@alpha (or use npx react-native-xtool@alpha).

Quick start

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)

Expo

npx create-expo-app@latest my-app --template default@sdk-58 && cd my-app
rn-xtool run   # with the iPhone plugged in

Bare React Native

npx @react-native-community/cli init MyApp --version 0.88.1 && cd MyApp
rn-xtool run   # with the iPhone plugged in

run = 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.

Daily loop

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 --clear forces a Metro cache reset.
  • run --network installs over Wi‑Fi, no cable, after a one-time USB pairing (docs/wifi-install.md).

CocoaPods binaries

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, build names 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.json at 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 reaches patches/.
  • Disk: before the first download, build checks 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 pods step makes no request, so a rebuild works without internet (with ios-xtool/.build kept; with no network at all, set lanIp in rn-xtool.config.json). "exclude" in rn-xtool.config.json still builds the app without the library.

Details, every message and what to do: docs/troubleshooting.md.

Commands

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.

Configuration

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).

Limits

  • The Metro port and LAN IP are baked into the app: if either changes, rebuild and reinstall (run does 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 (no actool on Linux); the app opens Metro by itself from its second launch, and the link and QR code from install cover the first one (details).
  • The app icon comes from the AppIcon set 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; .xcconfig files, capabilities, script phases, storyboards, asset catalogs (except the app icon) and .xib files are not used; entitlements come from the Debug CODE_SIGN_ENTITLEMENTS file (details).
  • Metal shaders are not compiled on Linux. react-native-svg's filters use the prebuilt *.metallib files it ships, which reach the app in RNSVGFilters.bundle (checked on a physical iPhone on 2026-11-05).
  • doctor --project and build refuse 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.allow in rn-xtool.config.json builds 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).

Learn more

Contributing

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).

License

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.

About

Build Expo and bare React Native iOS dev builds on Linux and install them on a real iPhone, no Mac needed

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages