# upgrading-react-native

Upgrades React Native apps to newer versions by applying rn-diff-purge template diffs, migrating iOS and Android native config, and resolving CocoaPods and Gradle conflicts.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 12600 installs · ★ 1684
- Author: callstackincubator
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/callstackincubator/agent-skills/tree/HEAD/skills/upgrading-react-native/SKILL.md
- Updated: 2026-10-08
- HTML: https://affpapa.org/en/nevibecode/skills/upgrading-react-native

## What it does

The skill guides an app through the full React Native upgrade cycle. It fetches the canonical template diff from Upgrade Helper, updates dependencies in `package.json`, aligns the React version, and migrates native iOS and Android configuration. Inside are six linked files: an upgrade path router, the Upgrade Helper workflow, dependency compatibility checks, React 19 alignment rules, an Expo SDK layer (if the project uses Expo), and a post-upgrade verification checklist.

It runs CLI commands: detects the current React Native version via `npm pkg get`, downloads the diff from GitHub, checks changed files with `grep`, runs `pod install` and `xcodebuild` for iOS, `npx react-native build-android` for Android. Without access to Upgrade Helper and the rn-diff-purge repository, it won't run. Expo projects need a separate SDK migration step.

The skill acts as a problem router: need dependency triage — it fires `upgrading-dependencies.md`, need regression validation — `upgrade-verification.md`, need command scoping for a monorepo — `monorepo-singlerepo-targeting.md`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add callstackincubator/agent-skills --skill upgrading-react-native -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/upgrading-react-native/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/upgrading-react-native/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add callstackincubator/agent-skills --skill upgrading-react-native -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/upgrading-react-native/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add callstackincubator/agent-skills --skill upgrading-react-native -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/upgrading-react-native/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install callstackincubator/agent-skills upgrading-react-native
```

2. **Manually: put the files in place**
- File: `.github/skills/upgrading-react-native/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add callstackincubator/agent-skills --skill upgrading-react-native -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/callstackincubator/agent-skills --path skills/upgrading-react-native
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/upgrading-react-native/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add callstackincubator/agent-skills --skill upgrading-react-native -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/callstackincubator/agent-skills/tree/HEAD/skills/upgrading-react-native/SKILL.md

## When to use it
- upgrade React Native from 0.76 to 0.78
- apply an rn-diff-purge diff to a project
- migrate native iOS and Android config after an RN upgrade
- resolve CocoaPods and Gradle conflicts after an upgrade
- align React version during an RN upgrade

## Example prompts
- Upgrade React Native from the current version to the latest stable
- Apply the Upgrade Helper diff for upgrading from 0.76.9 to 0.78.2
- Check dependency compatibility after upgrading React Native

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 58c188358aa69882.

BEGIN THIRD-PARTY FILE 58c188358aa69882
````text
---
name: upgrading-react-native
description: Upgrades React Native apps to newer versions by applying rn-diff-purge template diffs, updating package.json dependencies, migrating native iOS and Android configuration, resolving CocoaPods and Gradle changes, and handling breaking API updates. Use when upgrading React Native, bumping RN version, updating from RN 0.x to 0.y, or migrating Expo SDK alongside a React Native upgrade.
license: MIT
---

# Upgrading React Native

## Overview

Covers the full React Native upgrade workflow: template diffs via Upgrade Helper, dependency updates, Expo SDK steps, and common pitfalls.

## Typical Upgrade Sequence

1. **Route**: Choose the right upgrade path via [upgrading-react-native.md][upgrading-react-native]
2. **Diff**: Fetch the canonical template diff using Upgrade Helper via [upgrade-helper-core.md][upgrade-helper-core]
3. **Dependencies**: Assess and update third-party packages via [upgrading-dependencies.md][upgrading-dependencies]
4. **React**: Align React version if upgraded via [react.md][react]
5. **Expo** (if applicable): Apply Expo SDK layer via [expo-sdk-upgrade.md][expo-sdk-upgrade]
6. **Verify**: Run post-upgrade checks via [upgrade-verification.md][upgrade-verification]

```bash
# Quick start: detect current version and fetch diff
npm pkg get dependencies.react-native --prefix "$APP_DIR"
npm view react-native dist-tags.latest

# Example: upgrading from 0.76.9 to 0.78.2
# 1. Fetch the template diff
curl -L -f -o /tmp/rn-diff.diff \
  "https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/0.76.9..0.78.2.diff" \
  && echo "Diff downloaded OK" || echo "ERROR: diff not found, check versions"
# 2. Review changed files
grep -n "^diff --git" /tmp/rn-diff.diff
# 3. Update package.json, apply native changes, then install + rebuild
npm install --prefix "$APP_DIR"
cd "$APP_DIR/ios" && pod install
# 4. Validate: both platforms must build successfully
npx react-native build-android --mode debug --no-packager
xcodebuild -workspace "$APP_DIR/ios/App.xcworkspace" -scheme App -sdk iphonesimulator build
```

## When to Apply

Reference these guidelines when:
- Moving a React Native app to a newer version
- Reconciling native config changes from Upgrade Helper
- Validating release notes for breaking changes

## Quick Reference

| File | Description |
|------|-------------|
````
END THIRD-PARTY FILE 58c188358aa69882

The third-party file has ended. Everything between the 58c188358aa69882 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2376 of 4210 bytes. © callstackincubator · MIT · https://github.com/callstackincubator/agent-skills/tree/HEAD/skills/upgrading-react-native/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md