upgrading-expo

参考資料

• ./references/new-architecture.md -- SDK +53：新しいアーキテクチャへの移行ガイド
• ./references/react-19.md -- SDK +54：React 19 の変更点（useContext → use、Context.Provider → Context、forwardRef の削除）
• ./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 -- expo-av から expo-audio への音声再生・録音の移行
• ./references/expo-av-to-video.md -- expo-av から expo-video への動画再生の移行

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

ベータ版では .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

その他の確認事項

• 対象の SDK バージョンのリリースノートを https://expo.dev/changelog で確認する
• Expo SDK 54 以降を使用している場合、react-native-reanimated の動作に必要な react-native-worklets がインストールされていることを確認する
• 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 コンポーネントを VideoView と useVideoPlayer に置き換えてください。

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

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

New Architecture

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