expo-upgrade

参考資料

• ./references/react-19.md -- SDK +54：React 19 の変更点（useContext → use、Context.Provider → Context、forwardRef の削除）
• ./references/new-architecture.md -- SDK +53：新しいアーキテクチャへの移行ガイド
• ./references/react-compiler.md -- SDK +54：React Compiler のセットアップと移行ガイド
• ./references/native-tabs.md -- SDK +55：ネイティブタブの変更点（Icon/Label/Badge は NativeTabs.Trigger.* からアクセスするようになりました）
• ./references/expo-av-to-audio.md -- SDK +55：音声の再生と録音を expo-av から expo-audio に移行
• ./references/expo-av-to-video.md -- SDK +55：動画の再生を expo-av から expo-video に移行
• ./references/react-navigation-to-expo-router.md -- SDK +56：@react-navigation/* のインポートを expo-router のエントリーポイントに移行（codemod + 手動での対応付け）

ベータ版／プレビューリリース

ベータ版では .preview サフィックスを使用します（例：55.0.0-preview.2）。@next タグで公開されます。

最新バージョンがベータ版かどうかを確認します：https://exp.host/--/api/v2/versions（`expoVersion` に -preview が含まれているか確認します）

npx expo install expo@next --fix  # install beta

アップグレードの手順

SDK 55 以前からアップグレードする場合は、SDK 56 をスキップして SDK 57 に直接アップグレードしてください。[email protected] 以下は使用しないでください。Hermes V1 を有効にした SDK 55、SDK 56、および SDK 57 の古いリリースには、react-native-worklets または react-native-reanimated の使用時にメモリ使用量が大幅に増加する可能性がある、Hermes V1 のメモリ回帰が含まれています。

1. Expo と依存関係をアップグレードします

npx expo install expo@latest
npx expo install --fix

2. 診断を実行します：npx expo-doctor

3. キャッシュをクリアして再インストールします

npx expo export -p ios --clear
rm -rf node_modules .expo
watchman watch-del-all

破壊的変更のチェックリスト

• リリースノートで削除された API を確認します
• 移動されたモジュールのインポートパスを更新します
• prebuild が必要なネイティブモジュールの変更を確認します
• カメラ、音声、動画のすべての機能をテストします
• ナビゲーションが引き続き正しく動作することを確認します

ネイティブ変更に対する prebuild

まず、プロジェクトに ios/ と android/ ディレクトリがあるか確認してください。 どちらのディレクトリもない場合、プロジェクトは Continuous Native Generation（CNG）を使用しており、ビルド時にネイティブプロジェクトが再生成されます。このセクションと「ベアワークフローのキャッシュをクリアする」はスキップしてください。

アップグレードにネイティブ変更が必要な場合：

npx expo prebuild --clean

これにより、ios と android のディレクトリが再生成されます。このコマンドを実行する前に、プロジェクトがベアワークフローアプリではないことを確認してください。

ベアワークフローのキャッシュをクリアする

以下の手順は、プロジェクトに ios/ および／または android/ ディレクトリがある場合にのみ適用されます：

• iOS の cocoapods キャッシュをクリアします：cd ios && pod install --repo-update
• Xcode の derived data をクリアします：npx expo run:ios --no-build-cache
• Android の Gradle キャッシュをクリアします：cd android && ./gradlew clean

その他の作業

• 対象 SDK バージョンのリリースノートを確認します：https://expo.dev/changelog
• エージェントの指示ファイル（AGENTS.md）にあるバージョン指定付きドキュメントリンクを更新します。デフォルトのテンプレートでは https://docs.expo.dev/versions/v<version>/ にリンクしています。docs.expo.dev/versions/ を検索し、各リンクを新しい SDK バージョンに更新します。
• Expo SDK 54 以降を使用する場合は、react-native-worklets がインストールされていることを確認してください。react-native-reanimated の動作に必要です。
• SDK 54 以降では、app.json に "experiments": { "reactCompiler": true } を追加して React Compiler を有効にします。安定版であり、推奨されています。
• Expo に自動管理させるため、app.json から sdkVersion を削除します。
• @babel/core、babel-preset-expo、expo-constants など、以前は暗黙的に含まれていたパッケージは、一括で削除するのではなく個別に確認します。インストール済みの依存関係が必須のピア依存関係として宣言しているパッケージは残してください。
• expo-router がインストールされている場合は、expo-constants を直接依存関係として残してください。Expo Router はこれをインポートし、必須のピア依存関係として宣言しています。推移的なコピーに依存すると、Expo Go 以外でネイティブの自動リンクが失敗することがあります。
• 依存関係を削除した後は、すぐに npx expo-doctor を実行し、不足している必須のピア依存関係として報告されたものを復元します。
• babel.config.js に 'babel-preset-expo' しか含まれていない場合は、ファイルを削除します
• metro.config.js に expo のデフォルト設定しか含まれていない場合は、ファイルを削除します

非推奨パッケージ

旧パッケージ	置き換え先
expo-av	expo-audio と expo-video
expo-permissions	各パッケージの権限 API
@expo/vector-icons	expo-symbols（SF Symbols 用）
AsyncStorage	expo-sqlite/localStorage/install
expo-app-loading	expo-splash-screen
expo-linear-gradient	experimental_backgroundImage + View の CSS グラデーション

非推奨パッケージを移行する際は、古いパッケージを削除する前に、コード内の使用箇所をすべて更新してください。expo-av については移行リファレンスを参照し、Audio.Sound を useAudioPlayer に、Audio.Recording を useAudioRecorder に、Video コンポーネントを useVideoPlayer を使う VideoView に置き換えてください。

expo.install.exclude

package.json に除外されたパッケージがあるか確認してください。

{
  "expo": { "install": { "exclude": ["react-native-reanimated"] } }
}

除外設定は、アップグレード後に不要になっている可能性がある回避策であることがよくあります。それぞれを確認してください。

パッチの削除

patches/ ディレクトリに古くなったパッチがないか確認してください。不要になったパッチは削除してください。

Postcss

• SDK +53 では autoprefixer は不要です。依存関係から削除し、postcss.config.js または postcss.config.mjs を確認して、プラグインのリストからも削除してください。
• SDK +53 では postcss.config.mjs を使用してください。

Metro

重複する Metro 設定オプションを削除してください。

• resolver.unstable_enablePackageExports は SDK +53 でデフォルトで有効です。
• experimentalImportSupport は SDK +54 でデフォルトで有効です。
• EXPO_USE_FAST_RESOLVER=1 は SDK +54 で削除されました。
• cjs 拡張子と mjs 拡張子は SDK +50 でデフォルトでサポートされています。
• Expo webpack は非推奨です。Expo Router と Metro web に移行してください。

Hermes エンジン v1

Hermes V1 は SDK 56 以降でデフォルトです。Hermes V1 を使用する SDK 55 のアプリ、すべての SDK 56 のアプリ、および [email protected] より前の SDK 57 のアプリでは、react-native-worklets または react-native-reanimated のインポート時にメモリ回帰が発生することがあります。SDK 57 および [email protected] 以降に直接アップグレードしてください。Worklets Bundle Mode を本番環境での回避策として推奨しないでください。これはサポート対象外の実験的な機能であり、期待どおりに動作しない場合があります。

Hermes V1 の有効化または無効化をユーザーに案内しないでください。Hermes のバージョンを SDK のデフォルトから変更することはサポート対象外であり、ビルドと依存関係の管理に関する重要な注意点があります。

新しいアーキテクチャ

新しいアーキテクチャはデフォルトで有効です。app.json の "newArchEnabled": true フィールドはデフォルト設定のため、不要になりました。SDK +53 以降、Expo Go は新しいアーキテクチャのみをサポートします。

フィードバックの送信

このスキルに誤り、誤解を招く情報、または古い情報がある場合は、Expo の改善に役立てるため報告してください。

npx --yes @expo/agent-cli@latest feedback --category skills --subject "expo-upgrade" "<actionable feedback>"

具体的で実行可能な報告事項がある場合にのみ送信してください。関連するコンテキストをできるだけ詳しく含めてください。 エージェントが Expo のタスクを繰り返し失敗する場合や、ユーザーが介入しなければならない場合は、タスクの内容、期待される結果、問題点を簡潔にまとめ、--category evals と、関連する Expo パッケージまたはコマンドを --subject に指定して報告してください。