upgrading-expo

参考資料

• ./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

アップグレードの手順

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

その他の確認事項

• https://expo.dev/changelog で、対象 SDK バージョンのリリースノートを確認します
• Expo SDK 54 以降を使用している場合は、react-native-worklets がインストールされていることを確認してください。react-native-reanimated の動作に必要です。
• app.json に "experiments": { "reactCompiler": true } を追加して、SDK 54 以降で React Compiler を有効にします。安定しており、推奨されています。
• Expo が自動的に管理できるように、app.json から sdkVersion を削除します
• 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	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 の設定オプションを削除します。

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

Hermes engine v1

SDK 55 以降では、ユーザーは Hermes engine v1 をオプトインして、ランタイムのパフォーマンスを向上できます。これには、expo-build-properties の設定プラグインで useHermesV1: true を設定する必要があり、特定のバージョンの hermes-compiler npm パッケージが必要になる場合があります。Hermes v1 は、今後の SDK リリースでデフォルトになる予定です。

New Architecture

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