react-native-communityreact-native-community/skills/upgrade-react-native/SKILL.md

upgrade-react-native

Skill27 starsChanged 3 months agoMITView on GitHub

Use when upgrading react-native to a newer version. Handles version bumps, native project changes (Android/iOS), dependency updates, and breaking change migration. Invoke with `/upgrade-react-native <version>`.

6 other projects use a version of this, 1 of them edited.

Adopted by

Most recently taken up by

Phaedra-Solutions/cursor-rulestheir own version, first seen Nov 8, 2026
ltatarev/skillstheir own version, first seen Nov 1, 2026
callstack/repackedited, first seen Oct 8, 2026
mybigday/whisper.rntheir own version, first seen Oct 8, 2026
mybigday/llama.rntheir own version, first seen Oct 8, 2026
Shopify/flash-listtheir own version, first seen Mar 24, 2026

Other versions6 projects use a version of this.
Word for word · 0
None found.
Edited · 1
callstack/repack★ 1.9k99% same
Wrote their own version · 5
Shopify/flash-list★ 7.2ksame name
mybigday/llama.rn★ 1.1ksame name
mybigday/whisper.rn★ 809same name
Phaedra-Solutions/cursor-rules★ 4same name
ltatarev/skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository2 other files it gives its agents.
- AGENTS.mdAGENTS.md
- migrate-to-strict-apiSkill

The file

We split this skill into the rules it gives an agent

11 rules. 0 are common, 7 are distinctive, and 4 are very specific to this project.

0
Common
Most of the 6 edited versions we read keep these.
7
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Follow every step below in order.
line 34
Very specific:
Read the project's root package.json and extract the react-native version from dependencies (or devDependencies).
line 38
Distinctive:
If the current version cannot be determined, stop and ask the user.
line 42
Distinctive:
Verify the target version exists by checking:
line 48
Very specific:
If the diff cannot be fetched (404), it may be because exact patch versions are not available.
line 69
Distinctive:
Before making any edits, review the entire diff and categorize changes:
line 93
Very specific:
When updating package.json, update the react-native version and any related dependencies mentioned in the diff (e.g.
line 126
Very specific:
Do NOT run npm install / yarn install / pod install automatically.
line 129
Distinctive:
If multiple major versions are compatible, prefer the latest stable version that supports the target React Native version.
line 160
Distinctive:
Ask the user which they prefer:
line 169
Distinctive:
After applying all changes, present the user with a checklist:
line 178

“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Upgrade React Native

Upgrade a React Native Community CLI project to a target version by fetching and applying the diff from the React Native Upgrade Helper.

[!Note] Expo users: For Expo projects or more complex upgrade scenarios, try:
expo/skills/upgrading-expo
callstackincubator/agent-skills/upgrading-react-native

Invocation

/upgrade-react-native <targetVersion>

<targetVersion> — the React Native version to upgrade to (e.g. 0.79.0).

Step-by-step procedure

Follow every step below in order. Do not skip steps.

1. Detect the current React Native version

Read the project's root package.json and extract the react-native version from dependencies (or devDependencies). Strip any semver range prefix (^, ~, >=, etc.) to get the exact current version string.

If the current version cannot be determined, stop and ask the user.

2. Validate the target version

The target version must be a valid semver string (e.g. 0.79.0).
It must be greater than the current version.
Verify the target version exists by checking:
```
https://raw.githubusercontent.com/react-native-community/rn-diff-purge/master/RELEASES
```
Fetch this file and confirm the target version is listed. If not, report the closest available versions and ask the user to choose.

3. Fetch the upgrade diff

Fetch the unified diff between the two versions:

https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/<currentVersion>..<targetVersion>.diff

For example, to upgrade from 0.73.0 to 0.74.0:

https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/0.73.0..0.74.0.diff

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. Migrate to the Strict TypeScript API (target >= 0.87)

React Native 0.87 makes the Strict TypeScript API the default. When the upgrade crosses this boundary (current version < 0.87, target >= 0.87) and the project uses TypeScript (a tsconfig.json exists), type-checking of the project is affected and this step is required — do not silently skip it.

Ask the user which they prefer:

Migrate now (recommended) — run the migrate-to-strict-api skill (/migrate-to-strict-api), which handles dependency compatibility, deep import rewriting, and known breaking type changes.
Defer with the temporary opt-out — add "customConditions": ["react-native", "react-native-legacy-deep-imports"] to compilerOptions in tsconfig.json, keeping both entries. Tell the user this opt-out is temporary and due for removal in a future release.

For target versions below 0.87, or projects without TypeScript, skip this step and do not suggest the migration unprompted.

9. 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
(TypeScript, target >= 0.87) Run npx tsc --noEmit to confirm the Strict TypeScript API migration or opt-out from step 8
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
migrate-to-strict-api — Companion skill for the Strict TypeScript API migration (default from 0.87)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free