If the diff cannot be fetched (404), it may be because exact patch versions are
not available. Try the nearest minor versions (e.g.
0.73.0
instead of
0.73.2
). Report what you tried and ask the user if needed.
4. Parse the diff and map file paths
The diff uses the template project name
RnDiffApp
. Map every path in the diff
to the actual project:
Diff path prefix
Actual project path
RnDiffApp/
Project root (
./
)
Additionally, replace occurrences of the template identifiers with the project's
actual names:
Template value
Replace with
RnDiffApp
The project's app name (from
app.json
→
name
, or the
name
field in
package.json
)
rndiffapp
Lowercase version of the project's app name
com.rndiffapp
The project's Android package name (from
android/app/build.gradle
or
android/app/src/main/AndroidManifest.xml
)
5. Review the diff and plan changes
Before making any edits, review the entire diff and categorize changes:
Direct applies
— files that exist in the project and whose original
content matches the diff's
-
lines. These can be applied as-is.
Conflicts
— files where the project's content has diverged from the
template (custom modifications). These need manual merging.
New files
— files in the diff that don't exist in the project yet. Create
them.
Deleted files
— files the diff removes. Delete them only if the project
hasn't added custom content to them.
Present this plan to the user before proceeding. Group changes by area:
Root config files
(
package.json
,
metro.config.js
,
.eslintrc.js
, etc.)
iOS native files
(
ios/
directory)
Android native files
(
android/
directory)
JavaScript/TypeScript source
(if any template source files changed)
Third-party native dependencies
(from step 7 — include any version bumps
identified there)
6. Apply changes
Apply the changes following the plan from step 5:
For
direct applies
edit the file to match the diff's
+
lines.
For
conflicts
apply the upgrade changes while preserving the project's
customizations. Use your judgement to merge. If uncertain, show both versions
and ask the user.
For
new files
create them at the mapped path.
For
deleted files
remove them.
Important considerations:
When updating
package.json
, update the
react-native
version and any
related dependencies mentioned in the diff (e.g.
react
,
@react-native/*
packages, Gradle versions, CocoaPods versions).
Do NOT run
npm install
/
yarn install
/
pod install
automatically.
Inform the user these steps are needed after the upgrade.
Refer to the
references
section for version-specific guidance
on breaking changes and migration notes.
7. Update third-party native dependencies
Scan the project's
dependencies
and
devDependencies
in
package.json
for
third-party React Native libraries that contain
native code
(i.e. they have
an
ios/
or
android/
directory, or are known native modules). Common examples
include
react-native-screens
,
react-native-reanimated
,
react-native-gesture-handler
,
@react-native-async-storage/async-storage
,
react-native-svg
,
react-native-safe-area-context
, etc.
For each candidate dependency:
Fetch the library's README
from its GitHub repository or npm page.
Look for a React Native version compatibility table or section
— many
native libraries document which versions of their package support which React
Native versions (e.g. a "Compatibility" or "Version Support" table).
If the README contains a compatibility table
that maps the target React
Native version to a specific library version, include that library version
bump in the upgrade plan.
If the README does not mention version compatibility with React Native
versions
, skip the library — do not guess or assume an upgrade is needed.
Present all proposed dependency bumps alongside the diff-based changes in step 5
(grouped under a
Third-party native dependencies
section). For each:
State the current version, the proposed version, and link to the compatibility
info you found.
If multiple major versions are compatible, prefer the latest stable version
that supports the target React Native version.
Apply these version bumps to
package.json
as part of step 6.
8. Post-upgrade checklist
After applying all changes, present the user with a checklist:
Run
npm install
or
yarn install
to update JS dependencies
Run
cd ios && bundle exec pod install
(or
npx pod-install
) to update
native iOS dependencies
Run a clean build for Android:
cd android && ./gradlew clean
Run a clean build for iOS:
cd ios && xcodebuild clean
Run the app on both platforms to verify it launches
Run the project's test suite
Review any conflict resolutions for correctness
Check the
React Native changelog
for additional breaking changes
Check the
Upgrade Helper web UI
for any supplementary notes
References
Consult these for version-specific migration guidance:
references/upgrade-helper-api.md
— How
to fetch diffs and version lists programmatically