diff --git a/skills/.claude-plugin/plugin.json b/skills/.claude-plugin/plugin.json new file mode 100644 index 000000000..3b103e5fa --- /dev/null +++ b/skills/.claude-plugin/plugin.json @@ -0,0 +1,16 @@ +{ + "name": "react-native-community-skills", + "version": "0.1.0", + "description": "Official skills for React Native Community CLI projects", + "owner": { + "name": "React Native Community", + "url": "https://github.com/react-native-community" + }, + "skills": [ + { + "name": "upgrade-react-native", + "source": "./upgrade-react-native", + "description": "Upgrade React Native versions in Community CLI projects using the upgrade helper diff." + } + ] +} diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 000000000..acd1e1047 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,37 @@ +# react-native-community-skills (experimental) + +Official Agent Skills for React Native Community CLI projects. + +## Available skills + +| Skill | Description | +|-------|-------------| +| [upgrade-react-native](./upgrade-react-native/) | Upgrade React Native versions using the upgrade helper diff | + +## Installation + +### Claude Code + +```sh +npx skills add https://github.com/react-native-community/cli/tree/main/skills +``` + +### Cursor + +Open **Settings → Rules & Commands → Project Rules → Add Rule → Remote Rule (GitHub)** and enter: + +``` +https://github.com/react-native-community/react-native-cli.git +``` + +Skills are auto-discovered by Cursor based on their descriptions. + +### Other agents + +```sh +npx skills add https://github.com/react-native-community/cli/tree/main/skills +``` + +## License + +MIT diff --git a/skills/upgrade-react-native/SKILL.md b/skills/upgrade-react-native/SKILL.md new file mode 100644 index 000000000..4a69222e2 --- /dev/null +++ b/skills/upgrade-react-native/SKILL.md @@ -0,0 +1,178 @@ +--- +name: upgrade-react-native +description: > + 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: 0.1.0 +license: MIT +--- + +# 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](https://react-native-community.github.io/upgrade-helper/). + +## Invocation + +``` +/upgrade-react-native +``` + +- `` — 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/...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: + +1. **Direct applies** — files that exist in the project and whose original + content matches the diff's `-` lines. These can be applied as-is. +2. **Conflicts** — files where the project's content has diverged from the + template (custom modifications). These need manual merging. +3. **New files** — files in the diff that don't exist in the project yet. Create + them. +4. **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](#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: + +1. **Fetch the library's README** from its GitHub repository or npm page. +2. **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). +3. **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. +4. **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](https://github.com/facebook/react-native/blob/main/CHANGELOG.md) for additional breaking changes +- [ ] Check the [Upgrade Helper web UI](https://react-native-community.github.io/upgrade-helper/?from=&to=) for any supplementary notes + +## References + +Consult these for version-specific migration guidance: + +- [references/upgrade-helper-api.md](./references/upgrade-helper-api.md) — How + to fetch diffs and version lists programmatically diff --git a/skills/upgrade-react-native/references/upgrade-helper-api.md b/skills/upgrade-react-native/references/upgrade-helper-api.md new file mode 100644 index 000000000..22be7240c --- /dev/null +++ b/skills/upgrade-react-native/references/upgrade-helper-api.md @@ -0,0 +1,68 @@ +# Upgrade Helper API Reference + +The [React Native Upgrade Helper](https://react-native-community.github.io/upgrade-helper/) +uses pre-computed diffs from +[react-native-community/rn-diff-purge](https://github.com/react-native-community/rn-diff-purge). + +## Endpoints + +All endpoints are plain HTTP GET requests with no authentication required. + +### List available versions + +``` +GET https://raw.githubusercontent.com/react-native-community/rn-diff-purge/master/RELEASES +``` + +Returns a plain-text file with one version per line. + +### Fetch a diff between two versions + +``` +GET https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/{fromVersion}..{toVersion}.diff +``` + +Returns a standard unified diff (same format as `git diff` output). + +**Example:** + +``` +https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/0.73.0..0.74.0.diff +``` + +### View a file at a specific version + +``` +GET https://raw.githubusercontent.com/react-native-community/rn-diff-purge/release/{version}/RnDiffApp/{path} +``` + +### GitHub compare view + +``` +https://github.com/react-native-community/rn-diff-purge/compare/release/{fromVersion}..release/{toVersion} +``` + +### Web UI with pre-filled versions + +``` +https://react-native-community.github.io/upgrade-helper/?from={fromVersion}&to={toVersion} +``` + +## Diff format notes + +- All file paths are prefixed with `RnDiffApp/` (the template project name). +- The default app name is `RnDiffApp` with Android package `com.rndiffapp`. +- When applying diffs, replace these template names with the actual project's + app name and package identifiers. +- Binary files (e.g. Gradle wrapper JAR) appear as binary patch deltas and + should be downloaded directly from the target version's branch instead of + applying the diff. + +## Platform variants + +| Platform | Repository | Diff URL pattern | +|----------|-----------|-----------------| +| React Native (iOS/Android) | `react-native-community/rn-diff-purge` | `diffs/{from}..{to}.diff` | +| React Native macOS | `acoates-ms/rnw-diff` | `diffs/mac/{from}..{to}.diff` | +| React Native Windows (C++) | `acoates-ms/rnw-diff` | `diffs/cpp/{from}..{to}.diff` | +| React Native Windows (C#) | `acoates-ms/rnw-diff` | `diffs/cs/{from}..{to}.diff` |