expo-sdk-upgrade
Moves every Pocket Arcade app to a new Expo SDK (57 to 58) or Xcode major together - trigger check, expo install --fix, root tools, overrides, Gesture Handler 3, Reanimated Jest resolver, enableSceneSupport. Use when an SDK or Xcode upgrade is due. Not for single packages (dependency-management).
- License 许可
- MIT
- 最近更新
- 2026-11-05
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- expo-sdk-upgrade
- description
- Moves every Pocket Arcade app to a new Expo SDK (57 to 58) or Xcode major together - trigger check, expo install --fix, root tools, overrides, Gesture Handler 3, Reanimated Jest resolver, enableSceneSupport. Use when an SDK or Xcode upgrade is due. Not for single packages (dependency-management).
02 资源文件 153
- 资产文件assets/expo-sdk-57-module-map.json4.2 KB
- 资产文件assets/expo-sdk-58-preview-module-map.json4.1 KB
- 资产文件assets/sdk-lines.json4.7 KB
- 资产文件assets/shared.json162 B
- 参考文档examples/sdk-move-report.md4.1 KB
- 参考文档references/runbook.md10.1 KB
- 参考文档references/sdk-58-changes.md16.1 KB
- 参考文档references/upgrade-policy.md7.6 KB
- 参考文档references/xcode-and-scene-support.md5.4 KB
- 脚本scripts/check-lib.mjs44.4 KB
- 脚本scripts/check-sdk-alignment.mjs28.7 KB
- 脚本scripts/check-sdk-trigger.mjs15.3 KB
- 脚本scripts/lib/assemble-fixtures.mjs2.8 KB
- 脚本scripts/lib/sdk.mjs6.2 KB
- 脚本scripts/selftest.mjs2.1 KB
- 脚本templates/shell-config/scene-support.test.ts1.5 KB
- 脚本templates/shell-config/scene-support.ts1.6 KB
- 脚本tests/fixtures/base-sdk57/apps/alpha/index.ts159 B
- 参考文档tests/fixtures/base-sdk57/apps/alpha/package.json416 B
- 其他tests/fixtures/base-sdk57/apps/alpha/src/placeholder.tsx144 B
- 脚本tests/fixtures/base-sdk57/apps/beta/index.ts158 B
- 参考文档tests/fixtures/base-sdk57/apps/beta/package.json415 B
- 其他tests/fixtures/base-sdk57/apps/beta/src/placeholder.tsx143 B
- 脚本tests/fixtures/base-sdk57/jest.config.js320 B
- 参考文档tests/fixtures/base-sdk57/package-lock.json1.1 KB
- 参考文档tests/fixtures/base-sdk57/package.json682 B
- 参考文档tests/fixtures/base-sdk57/packages/shell/package.json401 B
- 脚本tests/fixtures/base-sdk57/packages/shell/plugins/with-app-variant-marker.ts511 B
- 脚本tests/fixtures/base-sdk57/packages/shell/src/config/with-shell.ts336 B
- 脚本tests/fixtures/base-sdk57/packages/shell/src/game-host/use-board-gestures.ts405 B
- 其他tests/fixtures/base-sdk57/packages/shell/src/screens/home/home-screen.tsx376 B
- 脚本tests/fixtures/base-sdk57/packages/tooling/src/ios/toolchain.ts159 B
- 脚本tests/fixtures/base-sdk58/apps/alpha/index.ts159 B
- 参考文档tests/fixtures/base-sdk58/apps/alpha/package.json430 B
- 其他tests/fixtures/base-sdk58/apps/alpha/src/placeholder.tsx144 B
- 脚本tests/fixtures/base-sdk58/apps/beta/index.ts158 B
- 参考文档tests/fixtures/base-sdk58/apps/beta/package.json429 B
- 其他tests/fixtures/base-sdk58/apps/beta/src/placeholder.tsx143 B
- 脚本tests/fixtures/base-sdk58/jest.config.js469 B
- 参考文档tests/fixtures/base-sdk58/package-lock.json1.1 KB
- 参考文档tests/fixtures/base-sdk58/package.json729 B
- 参考文档tests/fixtures/base-sdk58/packages/shell/package.json401 B
- 脚本tests/fixtures/base-sdk58/packages/shell/plugins/with-app-variant-marker.ts505 B
- 脚本tests/fixtures/base-sdk58/packages/shell/src/config/with-shell.ts336 B
- 脚本tests/fixtures/base-sdk58/packages/shell/src/game-host/use-board-gestures.ts517 B
- 其他tests/fixtures/base-sdk58/packages/shell/src/screens/home/home-screen.tsx376 B
- 脚本tests/fixtures/base-sdk58/packages/tooling/src/ios/toolchain.ts159 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-android-catalog-drift/EXPECT.txt430 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-android-catalog-drift/mutation.json789 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-android-kotlin-drift/EXPECT.txt122 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-android-kotlin-drift/mutation.json715 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-android-pins-drift/EXPECT.txt178 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-android-pins-drift/mutation.json1005 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-app-drift/EXPECT.txt80 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-app-drift/mutation.json162 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-app-lockstep/EXPECT.txt88 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-app-lockstep/mutation.json119 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-duplicate-first-install/EXPECT.txt201 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-duplicate-first-install/mutation.json814 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-duplicate-native/EXPECT.txt73 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-duplicate-native/mutation.json222 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-jest-expo-58/EXPECT.txt61 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-jest-expo-58/mutation.json158 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-jest-preset/EXPECT.txt74 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-jest-preset/mutation.json174 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-module-map/EXPECT.txt62 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-module-map/mutation.json354 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-overrides/EXPECT.txt60 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-overrides/mutation.json148 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-plugin-import/EXPECT.txt165 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-plugin-import/mutation.json244 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-scene-not-wired/EXPECT.txt142 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-scene-not-wired/mutation.json3.6 KB
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-scene-old-expo/EXPECT.txt84 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-scene-old-expo/mutation.json556 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-stale-override/EXPECT.txt76 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-stale-override/mutation.json165 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-test-renderer/EXPECT.txt45 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-test-renderer/mutation.json161 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-typescript-7/EXPECT.txt30 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-typescript-7/mutation.json158 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-v3-hooks-on-v2/EXPECT.txt126 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-v3-hooks-on-v2/mutation.json311 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-xcode27-no-scene/EXPECT.txt132 B
- 参考文档tests/fixtures/check-sdk-alignment-57/bad-xcode27-no-scene/mutation.json137 B
- 参考文档tests/fixtures/check-sdk-alignment-57/good/mutation.json621 B
- 参考文档tests/fixtures/check-sdk-alignment-57/pass-android-lines/EXPECT.txt422 B
- 参考文档tests/fixtures/check-sdk-alignment-57/pass-android-lines/mutation.json1.5 KB
- 参考文档tests/fixtures/check-sdk-alignment-58/bad-android-line-missing/EXPECT.txt148 B
- 参考文档tests/fixtures/check-sdk-alignment-58/bad-android-line-missing/mutation.json491 B
- 参考文档tests/fixtures/check-sdk-alignment-58/bad-builder-left/EXPECT.txt95 B
- 参考文档tests/fixtures/check-sdk-alignment-58/bad-builder-left/mutation.json284 B
- 参考文档tests/fixtures/check-sdk-alignment-58/bad-jest-resolver-missing/EXPECT.txt79 B
- 参考文档tests/fixtures/check-sdk-alignment-58/bad-jest-resolver-missing/mutation.json156 B
- 参考文档tests/fixtures/check-sdk-alignment-58/bad-plugin-js/EXPECT.txt94 B
- 参考文档tests/fixtures/check-sdk-alignment-58/bad-plugin-js/mutation.json252 B
- 参考文档tests/fixtures/check-sdk-alignment-58/bad-react-19-2/EXPECT.txt63 B
- 参考文档tests/fixtures/check-sdk-alignment-58/bad-react-19-2/mutation.json320 B
- 参考文档tests/fixtures/check-sdk-alignment-58/bad-removed-api/EXPECT.txt78 B
- 参考文档tests/fixtures/check-sdk-alignment-58/bad-removed-api/mutation.json308 B
- 参考文档tests/fixtures/check-sdk-alignment-58/bad-scene-helper-left/EXPECT.txt63 B
- 参考文档tests/fixtures/check-sdk-alignment-58/bad-scene-helper-left/mutation.json1.8 KB
- 参考文档tests/fixtures/check-sdk-alignment-58/bad-scene-leftover/EXPECT.txt62 B
- 参考文档tests/fixtures/check-sdk-alignment-58/bad-scene-leftover/mutation.json237 B
- 参考文档tests/fixtures/check-sdk-alignment-58/bad-skia-approval/EXPECT.txt48 B
- 参考文档tests/fixtures/check-sdk-alignment-58/bad-skia-approval/mutation.json174 B
- 参考文档tests/fixtures/check-sdk-alignment-58/bad-stale-reanimated-override/EXPECT.txt76 B
- 参考文档tests/fixtures/check-sdk-alignment-58/bad-stale-reanimated-override/mutation.json165 B
- 参考文档tests/fixtures/check-sdk-alignment-58/bad-unknown-sdk/EXPECT.txt44 B
- 参考文档tests/fixtures/check-sdk-alignment-58/bad-unknown-sdk/mutation.json320 B
- 参考文档tests/fixtures/check-sdk-alignment-58/good/mutation.json3 B
- 参考文档tests/fixtures/check-sdk-alignment-readiness/bad-interaction-manager/EXPECT.txt139 B
- 参考文档tests/fixtures/check-sdk-alignment-readiness/bad-interaction-manager/mutation.json308 B
- 参考文档tests/fixtures/check-sdk-alignment-readiness/bad-modal-animated/EXPECT.txt85 B
- 参考文档tests/fixtures/check-sdk-alignment-readiness/bad-modal-animated/mutation.json165 B
- 参考文档tests/fixtures/check-sdk-alignment-readiness/bad-old-xcode/EXPECT.txt60 B
- 参考文档tests/fixtures/check-sdk-alignment-readiness/bad-old-xcode/mutation.json137 B
- 参考文档tests/fixtures/check-sdk-alignment-readiness/bad-statusbar/EXPECT.txt82 B
- 参考文档tests/fixtures/check-sdk-alignment-readiness/bad-statusbar/mutation.json326 B
- 参考文档tests/fixtures/check-sdk-alignment-readiness/good/mutation.json3 B
- 参考文档tests/fixtures/check-sdk-alignment-readiness/pass-android-line-todo/EXPECT.txt69 B
- 参考文档tests/fixtures/check-sdk-alignment-readiness/pass-android-line-todo/mutation.json1.5 KB
- 参考文档tests/fixtures/check-sdk-trigger/bad-overdue-no-tag/EXPECT.txt92 B
- 参考文档tests/fixtures/check-sdk-trigger/bad-overdue-no-tag/mutation.json94 B
- 参考文档tests/fixtures/check-sdk-trigger/bad-upgrade-due-by-the-hour/EXPECT.txt53 B
- 参考文档tests/fixtures/check-sdk-trigger/bad-upgrade-due-by-the-hour/mutation.json165 B
- 参考文档tests/fixtures/check-sdk-trigger/bad-upgrade-due/EXPECT.txt354 B
- 参考文档tests/fixtures/check-sdk-trigger/bad-upgrade-due/mutation.json3 B
- 参考文档tests/fixtures/check-sdk-trigger/bad-upgrade-overdue/EXPECT.txt264 B
- 参考文档tests/fixtures/check-sdk-trigger/bad-upgrade-overdue/mutation.json295 B
- 参考文档tests/fixtures/check-sdk-trigger/error-no-facts/ARGS.txt2 B
- 参考文档tests/fixtures/check-sdk-trigger/error-no-facts/EXPECT.txt107 B
- 参考文档tests/fixtures/check-sdk-trigger/error-no-facts/mutation.json3 B
- 参考文档tests/fixtures/check-sdk-trigger/error-no-latest/EXPECT.txt59 B
- 参考文档tests/fixtures/check-sdk-trigger/error-no-latest/mutation.json76 B
- 参考文档tests/fixtures/check-sdk-trigger/good/mutation.json298 B
- 参考文档tests/fixtures/check-sdk-trigger/pass-after-move/EXPECT.txt226 B
- 参考文档tests/fixtures/check-sdk-trigger/pass-after-move/mutation.json216 B
- 参考文档tests/fixtures/check-sdk-trigger/pass-not-stable/EXPECT.txt180 B
- 参考文档tests/fixtures/check-sdk-trigger/pass-not-stable/mutation.json298 B
- 参考文档tests/fixtures/check-sdk-trigger/pass-package-missing/EXPECT.txt141 B
- 参考文档tests/fixtures/check-sdk-trigger/pass-package-missing/mutation.json166 B
- 参考文档tests/fixtures/check-sdk-trigger/pass-package-young/EXPECT.txt264 B
- 参考文档tests/fixtures/check-sdk-trigger/pass-package-young/mutation.json202 B
- 参考文档tests/fixtures/check-sdk-trigger/pass-rn-tool-missing/EXPECT.txt140 B
- 参考文档tests/fixtures/check-sdk-trigger/pass-rn-tool-missing/mutation.json183 B
- 参考文档tests/fixtures/check-sdk-trigger/pass-too-young/EXPECT.txt244 B
- 参考文档tests/fixtures/check-sdk-trigger/pass-too-young/mutation.json165 B
- 参考文档tests/fixtures/check-sdk-trigger/pass-young-by-seconds/EXPECT.txt141 B
- 参考文档tests/fixtures/check-sdk-trigger/pass-young-by-seconds/mutation.json165 B
- 参考文档tests/fixtures/check-sdk-trigger/pass-young-by-the-hour/EXPECT.txt141 B
- 参考文档tests/fixtures/check-sdk-trigger/pass-young-by-the-hour/mutation.json165 B
- 参考文档tests/fixtures/trigger-facts/facts.json1.4 KB
03 SKILL.md 正文
Expo SDK upgrade
Moves all apps of the monorepo to the next Expo SDK (or the build Mac to another Xcode) in one proven step: only when the new SDK is stable and old enough, with every package, tool, override and code migration in one commit, and a checker that proves the repo sits on one SDK line.
Rules that must hold
- Move only when the trigger holds:
lateston npm is the new SDK and at least 7 days old, every package the repo takes from its module map is published and at least 7 days old (check-sdk-trigger.mjsreportsupgrade-due), and on a branch every app passes verify, simulator builds, E2E and the screenshot matrix, and every Android port its emulator build and Android E2E.RESULT: PASSfrom the trigger check means no move is due (stay);RESULT: FAIL [upgrade-due]means the move is due and not yet done. Why: previews break things, and the first patch releases fix what.0broke; an SDK is never urgent enough for a release-age exception. - Move all apps together, in one commit, on a branch. Why: Expo does not support two React Native versions in one monorepo, and one Shell serves every game.
- Move Expo-managed packages only with
npx expo install expo@~<version>thennpx expo install --fixin every app. Never hand-edit an Expo-managed specifier or installreact-native, React, Reanimated, Worklets, Skia or Gesture Handler by hand. Why: Expo tests one coherent native set per SDK. - Everything that follows the SDK moves in the same commit: the root tools in one
npm install -D(jest-expo,eslint-config-expo,@react-native/jest-preset,@react-native/eslint-plugin,@types/react,test-renderer), the rootoverrides(react,react-native,react-native-reanimated,react-native-worklets, and every existing Shell-peer key at the exact version the apps install),allowScripts, the code migrations, this skill'sassets/sdk-lines.json(with its Android line: compileSdk, AGP, NDK, Gradle, Kotlin, JDK) and module map, the Android pins inpackages/tooling/src/android/toolchain.ts, and thedependency-managementversions table (with its Android toolchain). Why: each one alone breaks the install (ERESOLVE), the tree (duplicate native modules) or a gate. - Held-back tools stay: TypeScript 6.0, Jest 29.7,
@types/jest29.5.14, ESLint 9 (Expo's related packages keep them for SDK 58). Why: each has its own trigger; two moves in one commit cannot be debugged. - Select Xcode by version through
DEVELOPER_DIR, neverxcode-select. SDK 58 needs Xcode 26.4 or newer, not Xcode 27; building SDK 57 with Xcode 27 needsios.enableSceneSupportfirst (expo 57.0.23+), and the move to SDK 58 removes it. Why: an iOS 27 SDK build on the application life cycle does not launch correctly on iOS 27. - Migrate every gesture to Gesture Handler 3 hooks as a whole (
use-board-gestures.ts, and the SettingsSliderinpackages/shell/src/ui/slider.tsx) in the move commit. Why: hook and builder gestures cannot be related. - Never loosen a gate or re-accept a golden or screenshot to get green. Every diff must be explained by the change list and committed with a
Gate-Change:trailer. Why: a silent visual regression ships to 26 games at once. - Read the new versions' release notes and versioned docs, never memory, and add every new finding to
references/sdk-58-changes.md(or the next SDK's file) in the move commit. - Stop and ask before the branch (one message with a default) and before merging or pushing. Installing Xcode, licences and
sudoare the owner's.
Workflow
- Read references/upgrade-policy.md: the current line, the trigger, what moves together, the Xcode policy.
- Check the trigger:
node ${CLAUDE_SKILL_DIR}/scripts/check-sdk-trigger.mjs . --online --save-facts reports/sdk-trigger.json(without network:--facts <saved file>; with neither it exits 2).RESULT: PASSmeans no move is due: itswaitlines (target-stable,target-age,package-age,package-missing) say why and from which day it can change; stop and, if asked, report "not yet" with that day (examples/sdk-move-report.md, message 1).RESULT: FAIL [upgrade-due]means the move is due and not yet done: keep itsplanlines and continue. - Start green (
npm run -s check:fast,npm run verify, cleangit status), then scan readiness:node ${CLAUDE_SKILL_DIR}/scripts/check-sdk-alignment.mjs . --target-sdk 58. Fix everyFAILon the current SDK in its own commit; thetodolines are the move commit's work list. - Tell the owner (message 2 of the example) and continue unless told to wait.
- Read references/sdk-58-changes.md in full, then follow references/runbook.md steps 5 to 16: branch,
npx expo installin every app, root tools in one command, overrides, approvals, code migrations (config plugin imports, Jest resolver and asset-registry mapping, Gesture Handler 3, scene-support removal), then this skill's data and the versions-table hand-off. - For an Xcode-only change (for example Xcode 27 while still on SDK 57) read references/xcode-and-scene-support.md and copy
templates/shell-config/scene-support.tsand its test intopackages/shell/src/config/; run the verification loop below with--xcode <version>iftoolchain.tshas not changed yet. - Verification loop (runbook "Verification loop"):
node ${CLAUDE_SKILL_DIR}/scripts/check-sdk-alignment.mjs .untilRESULT: PASS(eachFAILnames the file, the rule and the fix),npx expo install --checkandnpx expo-doctorin every app,npm ls react react-native react-native-reanimated react-native-worklets,npm run verify, then per app the clean prebuild, Release simulator build and launch, E2E and screenshots (hand-off toios-simulator-buildande2e-maestro), and for every app with an Android port the Android build of the upgrade,npm run build:android:emuandnpm run e2e:android(hand-off toandroid-emulator-buildande2e-maestro); open every diff. - Commit the move as one commit with its
Gate-Change:trailer (runbook "Commit, report, merge"), report with message 3 of the example, and merge or push only on the owner's go.
Definition of done
- [ ] Before the branch,
check-sdk-trigger.mjsreportedupgrade-dueand its facts are saved inreports/; after the movenode ${CLAUDE_SKILL_DIR}/scripts/check-sdk-trigger.mjs . --onlineprintsRESULT: PASSagain (no move due). - [ ] Every app declares the same
expospecifier and exactly the new module map's specifiers;npx expo install --checkandnpx expo-doctorpass in every app;npm lsshows one version ofreact,react-native,react-native-reanimatedandreact-native-worklets. - [ ] Root tools, overrides and
allowScriptsmoved in the same commit; TypeScript, Jest and ESLint did not. - [ ] Config plugin imports, the Jest config, the board gestures and scene support match the new SDK;
npm run verifyis green. - [ ] Every app's Release simulator build launched, E2E and the screenshot matrix passed, every Android port's
npm run build:android:emuprintedready (...)and itsnpm run e2e:androidpassed, and every golden or screenshot diff was looked at and explained. - [ ]
assets/sdk-lines.json(its Android line included), the module map and thedependency-managementversions table describe the new SDK. - [ ] The owner got the report; nothing was merged or pushed without the go.
- [ ]
node ${CLAUDE_SKILL_DIR}/scripts/check-sdk-alignment.mjs .printsRESULT: PASS
Anti-patterns
- Adopting a preview, beta or release candidate, or adding a
min-release-age-excludeto get an SDK early: wait for the trigger. - Moving one app first "to try it", or merging a half-moved repo: the whole move lives on one branch until it is green.
- Installing
jest-expoalone, then--legacy-peer-depsto silenceERESOLVE: install the root tools in one command. npm dedupeor deletingnode_modulesagainst duplicate native modules: set the overrides andnpm install; expo-doctor must show no duplicates.- Switching config plugins to
expo/config-pluginsbefore the move (SDK 57 cannot resolve it) or keepingexpo/config-plugins.jsafter it (SDK 58 resolves it toconfig-plugins.js.js). - Mocking Reanimated to quiet Jest: the mock loads the native initializers too; use the Reanimated resolver plus the asset-registry mapping.
- Mixing builder and hook gestures during the move: migrate
use-board-gestures.tscompletely. jest -uover every golden, or a new screenshot baseline without looking: open each diff; accept only what the change list explains.- Selecting Xcode 27 on SDK 57 without scene support, or with
sudo xcode-select. - Taking TypeScript 7, Jest 30, ESLint 10 or a Node LTS move along with the SDK.
Files in this skill
| File | What it is | Read/run when |
|---|---|---|
| references/upgrade-policy.md | Current and next SDK line, the three-part trigger, what moves together and what never does, Xcode policy, human steps, fact-check commands | Workflow step 1, and at session starts in an SDK window |
| references/sdk-58-changes.md | Every verified 57 to 58 change with its error text and fix: packages, root tools, overrides, config plugins, Jest, Gesture Handler 3, Reanimated, Skia, React 19.3, React Native 0.88 | Workflow step 5, and for each failing gate during the move |
| references/runbook.md | The ordered steps with commands, expected output, the verification loop, commit, failure table, rollback | Workflow steps 5, 7 and 8 |
| references/xcode-and-scene-support.md | Xcode selection, Xcode moves, scene support for SDK 57 with Xcode 27, its verification and removal | Workflow step 6, and on a scene-support or xcode failure |
| examples/sdk-move-report.md | The three owner messages (not yet, ready, done), the evidence list and the move commit | Workflow steps 2, 4 and 8 |
templates/shell-config/scene-support.ts |
withSceneSupport(plugins): merges ios.enableSceneSupport into the expo-build-properties entry (tested) |
Workflow step 6 (SDK 57 with Xcode 27) |
templates/shell-config/scene-support.test.ts |
Its Jest tests (4 cases) | Copied with the template |
assets/sdk-lines.json |
Per-SDK expectations: React, test-renderer and @types/react lines, held-back tools, Gesture Handler major, config-plugin import, Jest config lines, Xcode, the Android toolchain (compileSdk, targetSdk, minSdk, build tools, NDK, CMake, AGP, Gradle, Kotlin, JDK), removed React Native APIs | Read by the scripts; update in the move commit |
assets/expo-sdk-57-module-map.json |
Expo 57.0.25's bundledNativeModules.json (synced from the library, the same file in dependency-management and expo-sdk-upgrade; do not edit here) |
Read by the scripts when node_modules is absent |
assets/expo-sdk-58-preview-module-map.json |
Expo 58.0.0-preview.7's bundledNativeModules.json (replace with the stable map at the move) |
Read by the scripts when node_modules is absent |
scripts/check-sdk-trigger.mjs |
Is an SDK move due? From npm facts (--online or --facts): RESULT: PASS = no move due, with wait reasons and dates; FAIL [upgrade-due] = due and not yet done, with this repo's plan; exit 2 without facts |
Workflow step 2, at session starts in an SDK window, and after the move |
scripts/check-sdk-alignment.mjs |
Proves the repo sits on one SDK line (19 rules, among them android-toolchain: React Native's version catalog, the repo's Android pins and the Shell's expo-build-properties options on the line's Android entry); --target-sdk adds the readiness scan |
Workflow steps 3 and 7, and after any SDK-related change |
scripts/lib/sdk.mjs |
Shared helpers: repo manifests, module maps, version comparison, dates | Read only to change a script |
scripts/lib/assemble-fixtures.mjs |
Builds each self-test case from a base repo plus its mutation.json |
Read only to add a self-test case |
scripts/selftest.mjs |
Proves both scripts on SDK 57, readiness, SDK 58 and trigger cases: 34 planted alignment problems (4 of them Android line drift: catalog, pins, Kotlin, an SDK without an Android line), 2 passing Android cases (pass-android-lines, and pass-android-line-todo: the readiness scan lists the next SDK's missing Android line as a todo), 4 "move due" cases (due, due by the hour, overdue with and without its dist-tag), 8 "no move due" cases (pass-*) whose printed reason and moment are pinned (the 7 days are measured from --now, by default the current time, as npm measures them, never from a midnight; the moment is rounded up to the next minute, never printed earlier than the real one), and two exit-2 cases (error-*: no facts, no "latest" tag), all run by the shared runner |
After changing a script, an asset or a fixture |
scripts/check-lib.mjs |
Shared script helper, synced from the library (do not edit here) | Never by hand |
assets/shared.json |
Declares the shared files copied into this skill | When adding a shared file |
tests/fixtures/ |
Base repos for SDK 57 and 58, trigger facts, one mutation.json and EXPECT.txt per case (good, bad-*, and the trigger's pass-* and error-* outcome cases, with an optional ARGS.txt) |
When adding a rule |
Related skills
dependency-management- single-package changes, the versions table the move updates, the Node LTS move.board-gestures-and-input- theuse-board-gestures.tscontract the Gesture Handler 3 migration keeps.unit-and-component-tests- the Jest projects, setup file and mocks the move touches.golden-tests- reviewing and re-accepting board goldens after a Skia change.ios-simulator-build- clean prebuild, Release simulator builds, Xcode selection.android-emulator-build- the Android build of the upgrade (build:android:emu), JDK 17 and the SDK parts.e2e-maestro- E2E flows and the screenshot matrix on the branch.quality-gates-npm run verifyand theGate-Change:rules.git-commits-and-reporting- the move commit and the owner report.
04 同仓库更多 Skills
unit-and-component-tests
Sets up Jest and writes Pocket Arcade test code - three projects, RNTL 14 async via renderWithShell, root SDK mocks, fakes, fast-check, coverage, Stryker. Use when a test needs the Shell wrapper, a mock or a fake, or Jest fails. Not for the red-green loop (tdd-workflow) or goldens (golden-tests).
typescript-and-lint-rules
Enforces Pocket Arcade's strict TypeScript 6 tsconfigs, ESLint 9 flat config, Prettier and size limits. Use when writing or splitting .ts/.tsx or fixing a tsc or lint error. Not for gate wiring (quality-gates), names (naming-conventions) or import zones (architecture-and-boundaries).
demo-skill
Builds a demo. Use when testing the pitfall checker.
demo-skill
Builds a demo. Use when testing the pitfall checker.
troubleshooting-playbook
Diagnoses and fixes Pocket Arcade failures with a catalogue of 300+ known ones (symptom, cause, fix). Use when something errors, crashes, hangs or renders wrong, or an error or log needs explaining. Not for gate setup (quality-gates) or running builds (ios-simulator-build, ios-release-testflight).
toybox-visual-parity
Proves a built Pocket Arcade screen matches its Toybox design screenshot (light/dark, en/fa) and drives the fixes: capture, element gates, sheets, sign-off. Use when any screen is built or changed, or for visual parity, design match, screenshot compare. Not for building screens (toybox-screens).