upgrading-expo

使用するタイミング

Expo SDK のバージョンをアップグレードしたり、依存関係の問題を修正したりするためのガイドラインが必要な場合に、このスキルを使用してください。

参考資料

• ./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 は一度に 1 つずつ、明示的に選択したバージョンにアップグレードしてください。これらの参考資料に記載された SDK ラベルは過去の情報であるため、API を適用する前に、対象バージョンのリリースノートとインストール済みの型定義を確認してください。ネイティブの再生成によって変更が失われた場合は、チェックポイントから復元してください。

アップグレードの手順

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

# Replace TARGET with the next intended SDK version, not a floating latest
npx expo install expo@TARGET
npx expo install --fix

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

3. 診断で古いキャッシュが示された場合に限り、確認済みのプロジェクトルートから実行し、その後、プロジェクトのパッケージマネージャーで再インストールします

npx expo export -p ios --clear
npx expo start --clear
# Remove project-local caches only if needed; avoid global Watchman reset.

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

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

ネイティブ変更のための Prebuild

まず、ネイティブプロジェクトが生成されるものか、手動で管理されているものかを確認してください。ディレクトリが存在するかどうかだけでは判断できません。 どちらのディレクトリも存在しない場合、プロジェクトは 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 を削除する
• 依存関係は、直接のインポート、設定での使用、対象 SDK の要件を確認してから削除してください。expo-constants は直接使用されている場合があります。
• babel.config.js に 'babel-preset-expo' しか含まれていない場合は、ファイルを削除する
• metro.config.js に expo のデフォルト設定しか含まれていない場合は、ファイルを削除する

非推奨パッケージ

古いパッケージ	置き換え先
expo-av	expo-audio と expo-video
expo-permissions	個別パッケージの権限 API
@expo/vector-icons	対応プラットフォームに適した意図的なアイコンの再設計を行う場合を除き、そのまま使用してください。SF Symbols はそのまま置き換えられるものではありません
AsyncStorage	永続化データ／API の移行が明示されていない限り、置き換えないでください
expo-app-loading	expo-splash-screen
expo-linear-gradient	グラデーションの代替手段を選ぶ前に、プラットフォームのサポート状況を確認してください

非推奨パッケージを移行する際は、古いパッケージを削除する前に、コード内の使用箇所をすべて更新してください。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 and Metro web に移行してください。

Hermes engine v1

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

新しいアーキテクチャ

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

制限事項

• タスクが上流製品または API の対象範囲に明確に合致する場合にのみ、このスキルを使用してください。
• 変更を行う前に、コマンド、API の動作、料金、クォータ、認証情報、デプロイによる影響を、最新の公式ドキュメントで確認してください。
• 生成された例を、環境固有のテスト、セキュリティレビュー、破壊的または高額な操作に対するユーザーの承認の代わりとして扱わないでください。