admin/openclaw-master-skills
1
0
Fork 0
mirror of https://github.com/LeoYeAI/openclaw-master-skills.git synced 2026-07-27 22:15:43 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
openclaw-master-skills/skills/upgrading-react-native/references/upgrade-helper-core.md
T

6.4 KiB
Raw Permalink Blame History

title, impact, tags
title impact tags
Upgrade Helper Core Workflow HIGH react-native, upgrade-helper, rn-diff-purge, ios, android

Skill: Upgrade Helper Core Workflow

Reliable, framework-agnostic workflow for React Native upgrades using Upgrade Helper and rn-diff-purge.

Run shared environment checks first in upgrading-react-native.md under Prerequisites (All Upgrade Paths).

Quick Commands

npm pkg get dependencies.react-native devDependencies.react-native --prefix "$APP_DIR"
npm view react-native dist-tags.latest
curl -L "https://raw.githubusercontent.com/react-native-community/rn-diff-purge/master/RELEASES"
curl -L -o /tmp/rn-diff-<current_version>..<target_version>.diff "https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/<current_version>..<target_version>.diff"
grep -n "^diff --git" /tmp/rn-diff-<current_version>..<target_version>.diff

Upgrade Helper API (Inline Reference)

  • List supported versions:
    • https://raw.githubusercontent.com/react-native-community/rn-diff-purge/master/RELEASES
  • Fetch raw unified diff:
    • https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/<current_version>..<target_version>.diff
  • GitHub compare view:
    • https://github.com/react-native-community/rn-diff-purge/compare/release/<current_version>..release/<target_version>
  • Upgrade Helper UI:
    • https://react-native-community.github.io/upgrade-helper/?from=<current_version>&to=<target_version>
  • Path mapping note:
    • Diff paths are prefixed with RnDiffApp/; remap to your app paths and package names.

Inputs

  • APP_DIR: app package path (. for single-package repos)
  • current_version: current React Native version
  • target_version: target React Native version (latest by default)

Reliable Workflow

  1. Detect app and versions.
    • Read react-native from APP_DIR/package.json.
    • Resolve target via npm view react-native dist-tags.latest unless user provides one.
  2. Validate target_version exists.
    • Check RELEASES from rn-diff-purge and confirm target_version is listed.
    • If missing, stop and ask user to choose one of available versions.
  3. Collect canonical sources.
    • Upgrade Helper URL.
    • rn-diff-purge raw diff.
  4. Fetch diff with fallback.
    • Try exact raw diff: <current_version>..<target_version>.
    • If 404, try nearest available patch versions and report what was attempted.
    • If no available pair works, stop and ask user for target adjustment.
  5. Build dependency baseline from rn-diff-purge first.
    • Start with the RnDiffApp/package.json diff for the exact version pair.
    • Do not manually install RN packages one-by-one before this baseline is captured.
  6. Publish a short execution plan before edits.
    • Include ordered phases: dependency baseline, one-pass install, native/tooling merges, verification.
    • If dependency migrations are ambiguous, ask for user confirmation before modifying package choices.
  7. Run dependency risk planning.
  8. Apply dependency updates in one pass.
    • Update APP_DIR/package.json (and lockfile) from the baseline plus approved migrations.
    • Run exactly one install command with the repo's package manager (npm install, yarn install, pnpm install, or bun install).
    • Avoid piecemeal installs such as repeated npm install <pkg> unless explicitly requested.
  9. Build a change checklist from diff.
    • Group by JS/TS, iOS, Android, tooling.
    • Skip template-only UI (App.tsx) unless explicitly requested.
    • Skip template-only dependencies (@react-native/new-app-screen) unless they exist in the app.
  10. Apply diff safely.
  • Treat RnDiffApp as placeholder; remap app/package names.
  • Merge, do not overwrite project-specific customizations.
  1. Sync native deps.
  • Run iOS pods in APP_DIR/ios.
  1. Validate and gate completion.

Stop Conditions

  • Missing react-native dependency in target package.
  • Diff source unavailable and no fallback available.
  • Unresolved native merge conflicts in iOS/Android entry files.

Reliability Rules

  • Keep operations version-pair scoped (current_version -> target_version).
  • Prefer official sources over ad-hoc guides.
  • Record every manual deviation from Upgrade Helper.
  • Do not run Expo-specific commands here.

Common Pitfalls

  • Upgrading an Expo project with only RN CLI steps: apply the Expo layer (expo-sdk-upgrade.md).
  • Skipping the Upgrade Helper: leads to missed native config changes.
  • Treating RnDiffApp paths as literal project paths.
  • Copying the entire template wholesale: use the diff as a guide and merge only needed changes.
  • Using the wrong changelog: 0.7x changes live in CHANGELOG-0.7x.md.
  • Running the wrong package manager: always match the repo lockfile.
  • Forgetting CocoaPods: iOS builds will fail without pod install.
  • Not updating Android Gradle wrapper binary: update android/gradle/wrapper/gradle-wrapper.jar for the target RN version. Source template:
    • https://raw.githubusercontent.com/react-native-community/rn-diff-purge/release/<target_version>/RnDiffApp/android/gradle/wrapper/gradle-wrapper.jar
  • Flipper artifacts lingering after removal in v0.74: remove ReactNativeFlipper.kt and FLIPPER_VERSION when the target RN version drops Flipper.
  • Skipping platform rebuilds after Pod/Gradle changes.

Related Skills

Reference in New Issue View Git Blame Copy Permalink