upgrade-react-native

React Native のアップグレード

React Native Upgrade Helper から diff を取得して適用することで、React Native Community CLI プロジェクトを対象バージョンにアップグレードします。

メモ

Expo ユーザーの方へ: Expo プロジェクトや、より複雑なアップグレードのシナリオでは、次をお試しください:

• expo/skills/upgrading-expo
• callstackincubator/agent-skills/upgrading-react-native

呼び出し

/upgrade-react-native <targetVersion>

• <targetVersion> — アップグレード先の React Native バージョン（例: 0.79.0）。

手順

以下のすべての手順を順番に実行してください。手順を飛ばさないでください。

1. 現在の React Native バージョンを検出する

プロジェクトのルートにある package.json を読み、dependencies（または devDependencies）から react-native のバージョンを抽出します。semver の範囲指定プレフィックス（^、~、>= など）を除去して、正確な現在のバージョン文字列を取得します。

現在のバージョンを特定できない場合は、停止してユーザーに確認してください。

2. 対象バージョンを検証する

• 対象バージョンは有効な semver 文字列（例: 0.79.0）でなければなりません。
• 現在のバージョンより大きい必要があります。
• 次を確認して、対象バージョンが存在することを検証します:

  https://raw.githubusercontent.com/react-native-community/rn-diff-purge/master/RELEASES
  

  このファイルを取得し、対象バージョンが記載されていることを確認します。記載されていない場合は、利用可能な最も近いバージョンを報告し、ユーザーに選択を求めてください。

3. アップグレード diff を取得する

2 つのバージョン間の unified diff を取得します:

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

たとえば、0.73.0 から 0.74.0 にアップグレードする場合:

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

diff を取得できない場合（404）、正確なパッチバージョンが利用できないことが原因かもしれません。最も近いマイナーバージョン（例: 0.73.2 の代わりに 0.73.0）を試してください。試した内容を報告し、必要に応じてユーザーに確認してください。

4. diff を解析し、ファイルパスをマッピングする

diff ではテンプレートプロジェクト名 RnDiffApp が使用されています。diff 内のすべてのパスを実際のプロジェクトにマッピングします:

Diff のパスプレフィックス	実際のプロジェクトパス
RnDiffApp/	プロジェクトルート（./）

さらに、テンプレートの識別子の出現箇所をプロジェクトの実際の名前に置き換えます:

テンプレートの値	置き換え後
RnDiffApp	プロジェクトのアプリ名（app.json の name、または package.json の name フィールドから取得）
rndiffapp	プロジェクトのアプリ名を小文字にしたもの
com.rndiffapp	プロジェクトの Android パッケージ名（android/app/build.gradle または android/app/src/main/AndroidManifest.xml から取得）

5. diff を確認して変更を計画する

編集を行う前に、diff 全体を確認し、変更を分類します:

1. 直接適用 — プロジェクトに存在し、その元の内容が diff の - 行と一致するファイル。そのまま適用できます。
2. 競合 — プロジェクトの内容がテンプレートから乖離している（カスタム変更がある）ファイル。手動でのマージが必要です。
3. 新規ファイル — diff に含まれるが、まだプロジェクトに存在しないファイル。これらを作成します。
4. 削除されたファイル — diff が削除するファイル。プロジェクトが独自の内容を追加していない場合に限り削除します。

進める前に、この計画をユーザーに提示してください。変更は領域ごとにグループ化します:

• ルート設定ファイル（package.json、metro.config.js、.eslintrc.js など）
• iOS ネイティブファイル（ios/ ディレクトリ）
• Android ネイティブファイル（android/ ディレクトリ）
• JavaScript/TypeScript ソース（テンプレートのソースファイルに変更がある場合）
• サードパーティのネイティブ依存関係（手順 7 より — そこで特定されたバージョンアップをすべて含めます）

6. 変更を適用する

ステップ 5 の計画に従って変更を適用します。

• 直接適用の場合: diff の + 行に一致するようにファイルを編集します。
• 競合の場合: プロジェクトのカスタマイズを保持しつつ、アップグレードの変更を適用します。判断してマージしてください。不明な場合は、両方のバージョンを示してユーザーに確認します。
• 新規ファイルの場合: マッピングされたパスに作成します。
• 削除されたファイルの場合: 削除します。

重要な考慮事項:

• package.json を更新する際は、react-native のバージョンと、diff に記載されている関連する依存関係（例: react、@react-native/* パッケージ、Gradle のバージョン、CocoaPods のバージョン）を更新します。
• npm install / yarn install / pod install を自動的に実行しないでください。アップグレード後にこれらの手順が必要であることをユーザーに通知します。
• 破壊的変更と移行に関するバージョン固有のガイダンスについては、references セクションを参照してください。

7. サードパーティのネイティブ依存関係を更新する

package.json の dependencies と devDependencies をスキャンして、ネイティブコードを含むサードパーティの React Native ライブラリ（つまり、ios/ または android/ ディレクトリを持つもの、またはネイティブモジュールとして知られているもの）を探します。一般的な例としては、react-native-screens、react-native-reanimated、react-native-gesture-handler、@react-native-async-storage/async-storage、react-native-svg、react-native-safe-area-context などがあります。

各候補の依存関係について:

1. ライブラリの README を取得する — GitHub リポジトリまたは npm ページから取得します。
2. React Native のバージョン互換性テーブルまたはセクションを探す — 多くのネイティブライブラリは、どのパッケージバージョンがどの React Native バージョンをサポートするかを文書化しています（例: 「Compatibility」や「Version Support」テーブル）。
3. README に対象の React Native バージョンと特定のライブラリバージョンを対応付ける互換性テーブルがある場合、そのライブラリのバージョンアップをアップグレード計画に含めます。
4. README に React Native バージョンとの互換性についての記載がない場合、そのライブラリはスキップします — アップグレードが必要であると推測したり仮定したりしないでください。

提案するすべての依存関係のバージョンアップを、ステップ 5 の diff ベースの変更と並べて提示します（サードパーティのネイティブ依存関係セクションの下にグループ化します）。それぞれについて:

• 現在のバージョン、提案するバージョンを示し、見つけた互換性情報へのリンクを記載します。
• 複数のメジャーバージョンが互換性がある場合は、対象の React Native バージョンをサポートする最新の安定版を優先します。

これらのバージョンアップをステップ 6 の一環として package.json に適用します。

8. Strict TypeScript API への移行（ターゲット >= 0.87）

React Native 0.87 では、Strict TypeScript API がデフォルトになります。アップグレードがこの境界を越える場合（現在のバージョン < 0.87、ターゲット >= 0.87）で、プロジェクトが TypeScript を使用している場合（tsconfig.json が存在する場合）、プロジェクトの型チェックが影響を受け、このステップは必須です — 暗黙にスキップしないでください。

ユーザーにどちらを希望するか確認します:

1. 今すぐ移行する（推奨） — migrate-to-strict-api スキル（/migrate-to-strict-api）を実行します。これは依存関係の互換性、ディープインポートの書き換え、既知の破壊的な型変更を処理します。
2. 一時的なオプトアウトで先送りする — tsconfig.json の compilerOptions に "customConditions": ["react-native", "react-native-legacy-deep-imports"] を追加し、両方のエントリを保持します。このオプトアウトは一時的なもので、将来のリリースで削除される予定であることをユーザーに伝えます。

ターゲットバージョンが 0.87 未満の場合、または TypeScript を使用していないプロジェクトの場合は、このステップをスキップし、促されていないのに移行を提案しないでください。

9. アップグレード後のチェックリスト

すべての変更を適用した後、ユーザーにチェックリストを提示します。

• npm install または yarn install を実行して JS 依存関係を更新する
• cd ios && bundle exec pod install（または npx pod-install）を実行して ネイティブ iOS 依存関係を更新する
• Android のクリーンビルドを実行する: cd android && ./gradlew clean
• iOS のクリーンビルドを実行する: cd ios && xcodebuild clean
• 両方のプラットフォームでアプリを実行し、起動することを確認する
• プロジェクトのテストスイートを実行する
• (TypeScript、ターゲット >= 0.87) npx tsc --noEmit を実行して、手順 8 の Strict TypeScript API への移行またはオプトアウトを確認する
• 競合の解決内容が正しいかレビューする
• その他の破壊的変更がないか、React Native changelog を確認する
• 補足事項がないか、Upgrade Helper web UI を確認する

参考資料

バージョン固有の移行ガイダンスについては、以下を参照してください:

• references/upgrade-helper-api.md — 差分と バージョン一覧をプログラムで取得する方法
• migrate-to-strict-api — Strict TypeScript API への移行（0.87 以降デフォルト）のためのコンパニオンスキル