Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
c9f73a1
docs: design and plan for Expo SDK 56
WillyAntunez Nov 11, 2026
358ad95
feat: add the Expo SDK 56 line
WillyAntunez Nov 11, 2026
5b9a921
fix: gate the expo-font copy the build links
WillyAntunez Nov 11, 2026
494fc81
test: pin SDK 56 macros path and row order
WillyAntunez Nov 11, 2026
14f9744
chore: name the vendored plugin path in comments
WillyAntunez Nov 11, 2026
e92fd2c
docs: rule on three more SDK 56 failures
WillyAntunez Nov 11, 2026
6429c47
feat: patch expo-modules-jsi 56 for Swift 6.4
WillyAntunez Nov 11, 2026
0edeab0
feat: find NativeState.h in either jsi layout
WillyAntunez Nov 11, 2026
16ac65b
fix: drop 0.86.3 from the jsi step's errors
WillyAntunez Nov 11, 2026
8c9a3e7
fix: ask autolinking which expo-font is linked
WillyAntunez Nov 11, 2026
75381c3
fix: name the header with the bad include
WillyAntunez Nov 11, 2026
463198c
feat: stop on an unreadable jsi interface
WillyAntunez Nov 11, 2026
875ccbb
feat: build a readable ExpoModulesJSI interface
WillyAntunez Nov 11, 2026
215eb15
fix: skip gated modules autolinking excludes
WillyAntunez Nov 11, 2026
deaa8a0
docs: record the B1 exit for the jsi interface
WillyAntunez Nov 11, 2026
96c4f1c
feat: read the iOS floor from Expo podspecs
WillyAntunez Nov 11, 2026
25f0f63
fix: cap a podspec's iOS floor at the app's
WillyAntunez Nov 11, 2026
0206ab0
fix: skip only modules the app excludes
WillyAntunez Nov 11, 2026
64d50fd
fix: catch more unreadable interface shapes
WillyAntunez Nov 11, 2026
56b695c
fix: clear the jsi module cache on --clean
WillyAntunez Nov 12, 2026
f79162b
chore: stop exploring Expo SDK 56
WillyAntunez Nov 12, 2026
f7effb5
docs: document Expo SDK 56 support
WillyAntunez Nov 12, 2026
eb4610e
fix: explain a cache left by a killed build
WillyAntunez Nov 12, 2026
401ed4c
fix: warn when autolinking cannot be asked
WillyAntunez Nov 12, 2026
c109485
docs: name SDK 56 and hybrid where they apply
WillyAntunez Nov 12, 2026
7ee3a96
refactor: keep jsi and plugin helpers private
WillyAntunez Nov 12, 2026
e64925d
fix: explain a bad module cache at install
WillyAntunez Nov 12, 2026
f3a0901
docs: correct the interrupted-build remedies
WillyAntunez Nov 12, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/drift-watch.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
# Daily (23 5 * * *): each supported line gets a fresh project (the newest patch of its line), and the project gates,
# the bundled patches and the manifest rewrite are checked on it. Nothing is compiled: there is no Swift and no
# Darwin SDK here. One `drift` issue is kept per broken line; it is closed when the line is green again.
# Weekly (47 5 * * 1): a report-only exploration of older lines (Expo SDK 54-56, bare React Native 0.81-0.84). It
# Weekly (47 5 * * 1): a report-only exploration of older lines (Expo SDK 54-55, bare React Native 0.81-0.84). It
# writes a capability table to the run summary and opens no issue.
# By hand: workflow_dispatch with mode `daily` or `explore`; `drill` (a line id, such as bare-0.88) marks that line
# broken for one daily run, to test the issue path end to end.
Expand Down
75 changes: 75 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,65 @@ versions follow [Semantic Versioning](https://semver.org/) with `alpha` prerelea
and `doctor --project`: "The app target <name> takes its files from the synchronized folder <folder> (an Xcode 16
folder group); rn-xtool reads only the files a target lists. Convert the folder to a group (Xcode: Convert to
Group) so the target lists its files".
- Expo SDK 55 and older are refused with "Expo SDK <n> is not supported; rn-xtool supports SDK 56 (expo 56.0.24 or
newer 56.x), SDK 57 (expo 57.0.31 or newer 57.x) and SDK 58 or newer.", and `doctor --project` gives them its
`support comes with the translator` reason; SDK 56 was among the refused SDKs before.
- On Expo SDK 58 (and 56), and in hybrid apps (bare React Native with Expo modules, SDK 58), the version check reads
expo-file-system and expo-font where expo-modules-autolinking links them, as its own CLI answers (`resolve --platform
apple --json`, the question the Expo plugin asks), instead of under `node_modules/expo` only: the app's own top-level
copy, a dependency's copy, a `file:`-linked library's copy and the folders `expo.autolinking` settings add are read as
the build links them. A package autolinking does not link is skipped when a copy is installed and the app excludes it
(`expo.autolinking.exclude`, or the `exclude` of `expo.autolinking.apple`, else of `expo.autolinking.ios`), and stops
the check when it is installed and not excluded: "<package> is installed (<path>) but Expo's autolinking does not link
it for iOS, and the app does not exclude it: the build would succeed and the app would fail at launch with "Cannot
find native module". …". When that CLI cannot run (no answer within 20 seconds included), the check falls back to the
top-level copy when the app, or a package it lists, depends on it, else the copy under `expo`, and says so in one
line: "⚠ rn-xtool could not ask Expo's autolinking which expo-file-system and expo-font copies the build links
(<reason>), so it read their versions from node_modules: … The build asks autolinking again and may link another copy.
See …". See [troubleshooting.md](docs/troubleshooting.md#expo-sdk-58).
- The `jsi` step's missing-headers error names no React Native version: "ExpoModulesJSI needs React Native's headers
at <dir>, which does not exist. rnArtifactsDir must hold the adapted slots of the project's React Native version, as
rn-xtool's rn-artifacts step writes them."
- The vendored Expo plugin (SDK 56 and 57) gives each generated Expo package the highest of its `spm.config.json`
floor, the iOS deployment target its podspec declares and core's (edit P7), capped at the App target's iOS 16.4. A
module whose podspec asks for more prints, once after `rn-spm`, "⚠ <package>'s podspec asks for iOS <version>, and
rn-xtool builds the app for iOS 16.4, so <package> is compiled for iOS 16.4: its code that needs iOS <version> must
be behind an availability check (`if #available(iOS <version>, *)`). On a Mac, the app's deployment target would be
raised to iOS <version> instead." The SDK 57 reference app's packages stay at iOS 16.4. See
[vendor/expo-spm/README.md](vendor/expo-spm/README.md).
- The weekly drift exploration covers Expo SDK 54 and 55 (and bare React Native 0.81 to 0.84); SDK 56 moved to the
daily watch.

### Added
- Expo SDK 56 (expo 56.0.24 or newer 56.x, react-native 0.85.3), on SDK 57's route: the vendored Expo plugin, the
vendored React Native 0.88.0 scripts, React Native 0.85.3's adapted artifacts, and the `jsi` step before `rn-spm`.
Its set is a floor: at least expo 56.0.24, expo-modules-core 56.0.27, expo-modules-jsi 56.0.14,
expo-modules-autolinking 56.0.24, expo-file-system 56.0.11 and expo-font 56.0.7, each on SDK 56's line, with
react-native exactly 0.85.3. Below it the build stops with "Expo SDK 56 needs react-native 0.85.3 and at least expo
56.0.24, … expo-font 56.0.7; installed: …" and the remedy; a newer 56.x builds with "⚠ Newer than the Expo SDK 56 set
this rn-xtool release was verified with: …". `doctor --project` reads `Expo SDK 56: expo 56.0.24 (verified
56.0.24), react-native 0.85.3 (verified 0.85.3)`. Build-verified only: a fresh `default@sdk-56` template with
expo-dev-client builds (2026-11-11; 346 s cold, 65 s warm, `App.app` 140 MB with 14 frameworks, G4 passing), and SDK
56 has not been run on a device yet. Known on the template: its `ios.icon` is an Icon Composer icon, so the app has
no icon until `ios.icon` is a PNG, and ExpoModulesWorkletsAdapter is left out because ExpoModulesCore is
precompiled. See [how-it-works.md](docs/how-it-works.md#expo-sdk-56).
- `expo-modules-jsi+56.0.14.patch`, staged on SDK 56 only (also for a newer 56.x jsi): `expo.CppError`'s `message`
made internal so Swift 6.4 compiles it, and four conformances to the internal `JSIRepresentable` marked
`@_spi(Internal)`, as jsi 57.1.3 does, so Swift 6.4 writes a readable ExpoModulesJSI interface. When it does not
apply, the stop names the SDK 56 `"overrides"` block.
- The `jsi` step takes `NativeState.h` from either expo-modules-jsi layout (`include/Public` on jsi 57 and newer,
`include` on jsi 56), with every header it includes with quotes. A missing one stops the step: "expo-modules-jsi
<version> ships no NativeState.h (looked in <include>/Public and <include>); cannot make
ExpoModulesJSIHeaders.xcframework." or "<header> of expo-modules-jsi <version> includes "<name>", which is not next
to it in <folder>; cannot make ExpoModulesJSIHeaders.xcframework.".
- On Expo SDK 56 and 57 the `jsi` step reads the `ExpoModulesJSI.swiftinterface` it built and stops when an
`extension` line has an empty place in its list of protocols, which no Swift compiler parses: "The
ExpoModulesJSI.swiftinterface built for expo-modules-jsi <version> (<compiler>) has <n> lines no Swift compiler can
parse, for example line <line>: <text>. Every module that imports ExpoModulesJSI would fail to compile. …", naming
another Swift than 6.4 as the likely cause when it wrote the interface. Before, the build failed minutes later at
`xtool-build` with `expected type` errors. See
[troubleshooting.md](docs/troubleshooting.md#unreadable-expomodulesjsi-interface).
- The daily drift watch checks `expo-56/default` (`default@sdk-56`), and `-f drill=expo-56` drills it.
- The `precheck` build step, between `generate` and `xtool-build`: SwiftPM plans the generated package, the app's
includes are resolved again with the App target's full include list, `swiftc -typecheck` checks the Swift files and
`clang -fsyntax-only` each C-family file with the generated manifest's flags. When a Swift file imports a module
Expand Down Expand Up @@ -55,6 +112,24 @@ versions follow [Semantic Versioning](https://semver.org/) with `alpha` prerelea
- `rn-xtool doctor --report` has a `precheck:` line: `precheck: run (last build)`, `precheck: skipped with
--skip-precheck (last build)` or `precheck: not recorded`.

### Fixed
- A build interrupted during the `jsi` step (Ctrl-C, a closed terminal, a reboot) no longer breaks every later build,
`build --clean` included, with clang's "… .pcm' is not a valid module file". `build --clean` (and `run --clean`)
removes the jsi build's scratch, `ios-xtool/jsi-out/.jsi-build`, before the `jsi` step on every project that has one;
Expo's `expo prebuild --clean` leaves `ios-xtool` alone, so it stayed before. A `jsi` failure with that clang error
now adds "The jsi step stopped on a precompiled module file in ExpoModulesJSI's module cache that is empty or cut
short ("is not a valid module file"): a build interrupted during the jsi step leaves its module cache that way, and
the next builds keep reading it. Run `rm -rf ios-xtool/jsi-out/.jsi-build` in the project folder, then `rn-xtool
build`, or run `rn-xtool build --clean`, …". A build interrupted during `xtool-build` leaves the app build's module
cache, under `ios-xtool/.build`, the same way, and on Expo `build --clean` keeps that folder: an `xtool-build` failure
(at `build`, `install` or `install --network`) with that clang error now adds "xtool dev build stopped on a
precompiled module file in the app build's module cache (ios-xtool/.build) that is empty or cut short ("is not a valid
module file"): … Run `rm -rf ios-xtool/.build` in the project folder, then `rn-xtool build`: its xtool-build starts
cold and takes several minutes. …". A file clang names anywhere else gets no paragraph. The `jsi` and `xtool-build`
steps' output now goes through a pipe, so rn-xtool can read it: SwiftPM prints each progress update (`[n/m] Compiling
…`) on a line of its own instead of redrawing one line, and its errors without colour. See
[troubleshooting.md](docs/troubleshooting.md#interrupted-build).

## [0.1.0-alpha.8] - 2026-11-09

### Upgrading from 0.1.0-alpha.7
Expand Down
12 changes: 7 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,11 @@ Demo video coming soon.
| --- | --- |
| Expo SDK 58 (expo 58.0.21 or newer 58.x, react-native 0.88.1) | ✅ [details](docs/how-it-works.md#expo-sdk-58) |
| Expo SDK 57 (expo 57.0.31 or newer 57.x, react-native 0.86.3) | ✅ [details](docs/how-it-works.md#expo-sdk-57) |
| Expo SDK 56 (expo 56.0.24 or newer 56.x, react-native 0.85.3; build-verified only) | ✅ [details](docs/how-it-works.md#expo-sdk-56) |
| Bare React Native 0.88.x from 0.88.0 (`@react-native-community/cli init`) | ✅ [details](docs/bare-react-native.md) |
| 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](docs/bare-react-native.md#supported-react-native-versions) |
| Bare React Native + Expo modules (hybrid), React Native 0.88.1 | ✅ [details](docs/bare-react-native.md#hybrid-bare--expo-modules) |
| 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) |
| Expo SDK 54–55, 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) |
Expand All @@ -36,9 +37,10 @@ Bare React Native versions: 0.85.x from 0.85.0, 0.86.x from 0.86.2, 0.87.x from
run on a device), see
[Supported React Native versions](docs/bare-react-native.md#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](docs/troubleshooting.md#newer-than-the-verified-versions)).
with one error naming these floors. Expo SDK 56, 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.85.3 on SDK 56, 0.86.3 on SDK 57, 0.88.1 on
SDK 58) ([details](docs/troubleshooting.md#newer-than-the-verified-versions)). Expo SDK 56 is build-verified only: a
fresh default template builds (2026-11-11), and it has not been run on a device yet.

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
Expand Down Expand Up @@ -155,7 +157,7 @@ Details, every message and what to do: [docs/troubleshooting.md](docs/troublesho
| `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](docs/troubleshooting.md#reporting-a-problem)). |
| `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](docs/troubleshooting.md#precheck)). |
| `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. On both, the `jsi` step builds ExpoModulesJSI again from an empty scratch folder (`ios-xtool/jsi-out/.jsi-build`). `--skip-precheck` leaves the `precheck` step out, and the check of the app's own includes at build start warns instead of stopping ([details](docs/troubleshooting.md#precheck)). |
| `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](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`. |
Expand Down
9 changes: 6 additions & 3 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,15 @@ Wi‑Fi installs, troubleshooting, library compatibility, and the research and d
## Guides

- [how-it-works.md](how-it-works.md): what `setup` installs, the bundled patches, the build steps, how the SwiftPM
scripts are chosen, the Expo SDK 58 and 57 version floors and the precompiled framework check (G4), Expo SDK 57
through the vendored Expo SwiftPM plugin, the first-launch reload helper, dev-client discovery, mixed-language
scripts are chosen, the Expo SDK 58, 57 and 56 version floors and the precompiled framework check (G4), Expo SDK 57
and 56 through the vendored Expo SwiftPM plugin, the first-launch reload helper, dev-client discovery, mixed-language
manifests, CocoaPods-only libraries and reference timings.
- [bare-react-native.md](bare-react-native.md): bare React Native projects (0.85.x from 0.85.0, 0.86.x from 0.86.2,
0.87.x from 0.87.1, 0.88.x from 0.88.0) and 0.88.1 hybrids with Expo modules: supported versions, detection, what is
read from the Xcode project, sources, resources, Metro, limits.
- [wifi-install.md](wifi-install.md): installing over Wi‑Fi without the cable, WSL2 pair records, Wi‑Fi troubleshooting.
- [troubleshooting.md](troubleshooting.md): first-run checklist on the iPhone and fixes for common build, Metro and
signing problems, opening a dev-client app on Metro, the app icon, the Expo SDK 58 and 57 version messages, the
signing problems, opening a dev-client app on Metro, the app icon, the Expo SDK 58, 57 and 56 version messages, the
warnings on versions newer than the verified ones, and what each `doctor --project` line means.
- [libraries.md](libraries.md): library compatibility matrix (Expo and bare), tested on a physical iPhone.

Expand Down Expand Up @@ -68,7 +68,10 @@ Historical specs and implementation plans, kept as written (some in Spanish; the
React Native projects.
- [design/specs/2026-10-27-expo-sdk-57-design.md](design/specs/2026-10-27-expo-sdk-57-design.md): Expo SDK 57 through
a vendored Expo SwiftPM plugin.
- [design/specs/2026-11-11-expo-sdk-56-design.md](design/specs/2026-11-11-expo-sdk-56-design.md): Expo SDK 56 on SDK
57's route.
- [design/plans/2026-10-23-expo-xtool-cli.md](design/plans/2026-10-23-expo-xtool-cli.md): CLI implementation plan.
- [design/plans/2026-10-26-bare-react-native.md](design/plans/2026-10-26-bare-react-native.md): bare React Native
implementation plan.
- [design/plans/2026-10-28-expo-sdk-57.md](design/plans/2026-10-28-expo-sdk-57.md): Expo SDK 57 implementation plan.
- [design/plans/2026-11-11-expo-sdk-56.md](design/plans/2026-11-11-expo-sdk-56.md): Expo SDK 56 implementation plan.
Loading
Loading