Skip to content

Commit 6f0c2e7

Browse files
ignyxignyx
committed
chore: install upgrade-react-native agent skill
From https://skills.sh/react-native-community/skills/upgrade-react-native, suggested by https://reactnative.dev/blog/2026/02/11/react-native-0.84#upgrading
1 parent 78e33f3 commit 6f0c2e7

4 files changed

Lines changed: 264 additions & 0 deletions

File tree

‎.agents/skills/upgrade-react-native/SKILL.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
---
2+
name: upgrade-react-native
3+
description: >
4+
Use when upgrading react-native to a newer version. Handles version bumps,
5+
native project changes (Android/iOS), dependency updates, and breaking change
6+
migration. Invoke with `/upgrade-react-native <version>`.
7+
version: 0.1.0
8+
license: MIT
9+
---
10+
11+
# Upgrade React Native
12+
13+
Upgrade a React Native Community CLI project to a target version by fetching
14+
and applying the diff from the
15+
[React Native Upgrade Helper](https://react-native-community.github.io/upgrade-helper/).
16+
17+
<!-- LLM_EXCLUDE: Human-only context below -->
18+
> [!Note]
19+
> **Expo users:** For Expo projects or more complex upgrade scenarios, try:
20+
> - [expo/skills/upgrading-expo](https://skills.sh/expo/skills/upgrading-expo)
21+
> - [callstackincubator/agent-skills/upgrading-react-native](https://skills.sh/callstackincubator/agent-skills/upgrading-react-native)
22+
<!-- /LLM_EXCLUDE -->
23+
24+
## Invocation
25+
26+
```
27+
/upgrade-react-native <targetVersion>
28+
```
29+
30+
- `<targetVersion>` — the React Native version to upgrade to (e.g. `0.79.0`).
31+
32+
## Step-by-step procedure
33+
34+
Follow every step below **in order**. Do not skip steps.
35+
36+
### 1. Detect the current React Native version
37+
38+
Read the project's root `package.json` and extract the `react-native` version
39+
from `dependencies` (or `devDependencies`). Strip any semver range prefix
40+
(`^`, `~`, `>=`, etc.) to get the exact current version string.
41+
42+
If the current version cannot be determined, stop and ask the user.
43+
44+
### 2. Validate the target version
45+
46+
- The target version must be a valid semver string (e.g. `0.79.0`).
47+
- It must be **greater than** the current version.
48+
- Verify the target version exists by checking:
49+
```
50+
https://raw.githubusercontent.com/react-native-community/rn-diff-purge/master/RELEASES
51+
```
52+
Fetch this file and confirm the target version is listed. If not, report the
53+
closest available versions and ask the user to choose.
54+
55+
### 3. Fetch the upgrade diff
56+
57+
Fetch the unified diff between the two versions:
58+
59+
```
60+
https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/<currentVersion>..<targetVersion>.diff
61+
```
62+
63+
For example, to upgrade from `0.73.0` to `0.74.0`:
64+
65+
```
66+
https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/0.73.0..0.74.0.diff
67+
```
68+
69+
If the diff cannot be fetched (404), it may be because exact patch versions are
70+
not available. Try the nearest minor versions (e.g. `0.73.0` instead of
71+
`0.73.2`). Report what you tried and ask the user if needed.
72+
73+
### 4. Parse the diff and map file paths
74+
75+
The diff uses the template project name `RnDiffApp`. Map every path in the diff
76+
to the actual project:
77+
78+
| Diff path prefix | Actual project path |
79+
|------------------|---------------------|
80+
| `RnDiffApp/` | Project root (`./`) |
81+
82+
Additionally, replace occurrences of the template identifiers with the project's
83+
actual names:
84+
85+
| Template value | Replace with |
86+
|----------------|--------------|
87+
| `RnDiffApp` | The project's app name (from `app.json` → `name`, or the `name` field in `package.json`) |
88+
| `rndiffapp` | Lowercase version of the project's app name |
89+
| `com.rndiffapp` | The project's Android package name (from `android/app/build.gradle` or `android/app/src/main/AndroidManifest.xml`) |
90+
91+
### 5. Review the diff and plan changes
92+
93+
Before making any edits, review the entire diff and categorize changes:
94+
95+
1. **Direct applies** — files that exist in the project and whose original
96+
content matches the diff's `-` lines. These can be applied as-is.
97+
2. **Conflicts** — files where the project's content has diverged from the
98+
template (custom modifications). These need manual merging.
99+
3. **New files** — files in the diff that don't exist in the project yet. Create
100+
them.
101+
4. **Deleted files** — files the diff removes. Delete them only if the project
102+
hasn't added custom content to them.
103+
104+
Present this plan to the user before proceeding. Group changes by area:
105+
106+
- **Root config files** (`package.json`, `metro.config.js`, `.eslintrc.js`, etc.)
107+
- **iOS native files** (`ios/` directory)
108+
- **Android native files** (`android/` directory)
109+
- **JavaScript/TypeScript source** (if any template source files changed)
110+
- **Third-party native dependencies** (from step 7 — include any version bumps
111+
identified there)
112+
113+
### 6. Apply changes
114+
115+
Apply the changes following the plan from step 5:
116+
117+
- For **direct applies**: edit the file to match the diff's `+` lines.
118+
- For **conflicts**: apply the upgrade changes while preserving the project's
119+
customizations. Use your judgement to merge. If uncertain, show both versions
120+
and ask the user.
121+
- For **new files**: create them at the mapped path.
122+
- For **deleted files**: remove them.
123+
124+
**Important considerations:**
125+
126+
- When updating `package.json`, update the `react-native` version and any
127+
related dependencies mentioned in the diff (e.g. `react`, `@react-native/*`
128+
packages, Gradle versions, CocoaPods versions).
129+
- Do NOT run `npm install` / `yarn install` / `pod install` automatically.
130+
Inform the user these steps are needed after the upgrade.
131+
- Refer to the [references](#references) section for version-specific guidance
132+
on breaking changes and migration notes.
133+
134+
### 7. Update third-party native dependencies
135+
136+
Scan the project's `dependencies` and `devDependencies` in `package.json` for
137+
third-party React Native libraries that contain **native code** (i.e. they have
138+
an `ios/` or `android/` directory, or are known native modules). Common examples
139+
include `react-native-screens`, `react-native-reanimated`,
140+
`react-native-gesture-handler`, `@react-native-async-storage/async-storage`,
141+
`react-native-svg`, `react-native-safe-area-context`, etc.
142+
143+
For each candidate dependency:
144+
145+
1. **Fetch the library's README** from its GitHub repository or npm page.
146+
2. **Look for a React Native version compatibility table or section** — many
147+
native libraries document which versions of their package support which React
148+
Native versions (e.g. a "Compatibility" or "Version Support" table).
149+
3. **If the README contains a compatibility table** that maps the target React
150+
Native version to a specific library version, include that library version
151+
bump in the upgrade plan.
152+
4. **If the README does not mention version compatibility with React Native
153+
versions**, skip the library — do not guess or assume an upgrade is needed.
154+
155+
Present all proposed dependency bumps alongside the diff-based changes in step 5
156+
(grouped under a **Third-party native dependencies** section). For each:
157+
158+
- State the current version, the proposed version, and link to the compatibility
159+
info you found.
160+
- If multiple major versions are compatible, prefer the latest stable version
161+
that supports the target React Native version.
162+
163+
Apply these version bumps to `package.json` as part of step 6.
164+
165+
### 8. Post-upgrade checklist
166+
167+
After applying all changes, present the user with a checklist:
168+
169+
- [ ] Run `npm install` or `yarn install` to update JS dependencies
170+
- [ ] Run `cd ios && bundle exec pod install` (or `npx pod-install`) to update
171+
native iOS dependencies
172+
- [ ] Run a clean build for Android: `cd android && ./gradlew clean`
173+
- [ ] Run a clean build for iOS: `cd ios && xcodebuild clean`
174+
- [ ] Run the app on both platforms to verify it launches
175+
- [ ] Run the project's test suite
176+
- [ ] Review any conflict resolutions for correctness
177+
- [ ] Check the [React Native changelog](https://github.com/facebook/react-native/blob/main/CHANGELOG.md) for additional breaking changes
178+
- [ ] Check the [Upgrade Helper web UI](https://react-native-community.github.io/upgrade-helper/?from=<currentVersion>&to=<targetVersion>) for any supplementary notes
179+
180+
## References
181+
182+
Consult these for version-specific migration guidance:
183+
184+
- [references/upgrade-helper-api.md](./references/upgrade-helper-api.md) — How
185+
to fetch diffs and version lists programmatically

‎.agents/skills/upgrade-react-native/references/upgrade-helper-api.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Upgrade Helper API Reference
2+
3+
The [React Native Upgrade Helper](https://react-native-community.github.io/upgrade-helper/)
4+
uses pre-computed diffs from
5+
[react-native-community/rn-diff-purge](https://github.com/react-native-community/rn-diff-purge).
6+
7+
## Endpoints
8+
9+
All endpoints are plain HTTP GET requests with no authentication required.
10+
11+
### List available versions
12+
13+
```
14+
GET https://raw.githubusercontent.com/react-native-community/rn-diff-purge/master/RELEASES
15+
```
16+
17+
Returns a plain-text file with one version per line.
18+
19+
### Fetch a diff between two versions
20+
21+
```
22+
GET https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/{fromVersion}..{toVersion}.diff
23+
```
24+
25+
Returns a standard unified diff (same format as `git diff` output).
26+
27+
**Example:**
28+
29+
```
30+
https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/0.73.0..0.74.0.diff
31+
```
32+
33+
### View a file at a specific version
34+
35+
```
36+
GET https://raw.githubusercontent.com/react-native-community/rn-diff-purge/release/{version}/RnDiffApp/{path}
37+
```
38+
39+
### GitHub compare view
40+
41+
```
42+
https://github.com/react-native-community/rn-diff-purge/compare/release/{fromVersion}..release/{toVersion}
43+
```
44+
45+
### Web UI with pre-filled versions
46+
47+
```
48+
https://react-native-community.github.io/upgrade-helper/?from={fromVersion}&to={toVersion}
49+
```
50+
51+
## Diff format notes
52+
53+
- All file paths are prefixed with `RnDiffApp/` (the template project name).
54+
- The default app name is `RnDiffApp` with Android package `com.rndiffapp`.
55+
- When applying diffs, replace these template names with the actual project's
56+
app name and package identifiers.
57+
- Binary files (e.g. Gradle wrapper JAR) appear as binary patch deltas and
58+
should be downloaded directly from the target version's branch instead of
59+
applying the diff.
60+
61+
## Platform variants
62+
63+
| Platform | Repository | Diff URL pattern |
64+
|----------|-----------|-----------------|
65+
| React Native (iOS/Android) | `react-native-community/rn-diff-purge` | `diffs/{from}..{to}.diff` |
66+
| React Native macOS | `acoates-ms/rnw-diff` | `diffs/mac/{from}..{to}.diff` |
67+
| React Native Windows (C++) | `acoates-ms/rnw-diff` | `diffs/cpp/{from}..{to}.diff` |
68+
| React Native Windows (C#) | `acoates-ms/rnw-diff` | `diffs/cs/{from}..{to}.diff` |

‎.vibe/skills/upgrade-react-native‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../.agents/skills/upgrade-react-native

‎skills-lock.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"version": 1,
3+
"skills": {
4+
"upgrade-react-native": {
5+
"source": "react-native-community/skills",
6+
"sourceType": "github",
7+
"computedHash": "f120c3e4c5e696b147c24a953c18b0fabbf1fe46d0c8ab68db4fdb146e54075a"
8+
}
9+
}
10+
}

0 commit comments

Comments
 (0)