React Native のアップグレード

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

<!-- LLM_EXCLUDE: Human-only context below -->

[!Note] Expo ユーザー向け: Expo プロジェクトまたはより複雑なアップグレード情報については、以下をご覧ください:

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

<!-- /LLM_EXCLUDE -->

呼び出し方法

/upgrade-react-native <targetVersion>

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

ステップバイステップの手順

以下のステップを順序通りにすべて実行してください。ステップをスキップしないでください。

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

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

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

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

• 対象バージョンは有効なセマンティックバージョン文字列である必要があります（例: 0.79.0）
• 現在のバージョンより大きい必要があります
• 以下をチェックして対象バージョンの存在を確認します:

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

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

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

2つのバージョン間の統一差分を取得します:

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 バージョンとの互換性テーブルが含まれている場合、対象 React Native バージョンに対応するライブラリバージョンをプランに含めます。
4. README が React Native バージョンとのバージョン互換性について触れていない場合、ライブラリをスキップしてください — 推測や仮定でアップグレードが必要だと判断しないでください。

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

• 現在のバージョン、提案されるバージョン、および検出した互換性情報へのリンクを記載します。
• 複数のメジャーバージョンが互換性がある場合、対象 React Native バージョンをサポートする最新の安定バージョンを優先します。

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

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

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

• 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
• 両方のプラットフォームでアプリを実行して、起動することを確認
• プロジェクトのテストスイートを実行
• 競合の解決の正確性を確認
• React Native changelog で追加の破壊的変更を確認
• Upgrade Helper web UI で補足注釈を確認

参考資料

バージョン固有のマイグレーション指針については、以下を参照してください:

• references/upgrade-helper-api.md — diff とバージョンリストをプログラムで取得する方法