expo-upgrading-v55

参考資料

• ./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 の派生データをクリアします：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-reanimated の動作に必要な react-native-worklets がインストールされていることを確認します。
• app.json に "experiments": { "reactCompiler": true } を追加して、SDK 54 以降で React Compiler を有効にします。安定版であり、推奨されています。
• sdkVersion を app.json から削除し、Expo に自動管理させます
• package.json から暗黙的なパッケージを削除します：@babel/core、babel-preset-expo、expo-constants。
• 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	View の experimental_backgroundImage と 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 submit-expo-feedback@latest --category skills --subject "expo-upgrade" "<actionable feedback>"

具体的で実行可能な報告事項がある場合にのみ送信してください。関連する背景情報をできるだけ詳しく含めてください。 AI エージェントが Expo のタスクに何度も失敗した場合、またはユーザーが作業を引き継ぐ必要があった場合は、上記のコマンドを再利用せず、expo-skill-feedback スキルを読み込み、その eval-candidate フローに従ってください。