upgrading-expo

upgrading-expo スキルの概要

upgrading-expo スキルでできること

upgrading-expo スキルは、ありがちな「Expo をどうアップグレードすればいい？」という漠然とした質問よりも、見落としを減らしながら Expo SDK の更新を計画・実行できるようにするためのスキルです。焦点が当たっているのは実務で本当に必要な作業です。たとえば、コアパッケージの更新、依存関係のずれの修正、古いキャッシュの削除、そして React・New Architecture・Native Tabs・expo-av 移行まわりで起こりやすい破壊的変更の見極めなどです。

upgrading-expo を使うべき人

この upgrading-expo skill は、既存の Expo アプリを保守しているフロントエンド開発者、React Native チーム、AI エージェントに特に向いています。単なるリリースノートの要約ではなく、すでにあるプロジェクトに対して現実的なアップグレード手順が必要なときに最も役立ちます。

向いているケース:

• 近年の Expo SDK バージョン間でアップグレードしたい
• expo install --fix 実行後に install エラーや実行時の不具合が出た
• expo-av のように変更・分割されたパッケージから移行したい
• React 19 や Native Tabs など、SDK 固有の変更が自分のコードベースに影響するか確認したい

実際に解決したい課題

upgrading-expo for Frontend Development を検討しているユーザーが、まず素早く知りたいのはたいてい次の 3 点です。

1. 最初にどのコマンド順で実行すべきか
2. どの破壊的変更が自分のアプリに当たりそうか
3. 無駄なデバッグに入る前に、どのファイルや実装パターンを確認すべきか

このスキルの価値は、そうした判断材料を 1 か所にまとめ、具体的な移行リファレンスに結び付けてくれる点にあります。

一般的なアップグレード用プロンプトとの違い

普通のプロンプトでも「Expo を上げて doctor を回して」といった提案はできます。ですが upgrading-expo スキルはそこから一歩進み、リポジトリ内のバージョン連動の移行トピックまで拾ってくれます。たとえば次のようなものです。

• SDK 53+ における New Architecture のデフォルト化
• SDK 54 の React 19 変更
• SDK 54+ の React Compiler 設定
• SDK 55 の Native Tabs API 変更
• 音声・動画向けの expo-av 置き換えパス

そのため、広く React Native の不具合を探るようなプロンプトよりも、的を絞ったアップグレード作業に向いています。

インストール前に知っておきたいこと

このスキルは、自動化中心というよりガイド中心です。リポジトリを自動で調べてくれるスクリプトが入っているわけではありません。価値の源泉は、整理されたアップグレード手順と、自分のコードベースに適用できる参照ドキュメントにあります。ボタン 1 つで移行してくれるツールが欲しいなら、これは違います。逆に、密度の高いアップグレードチェックリストと具体的な移行例が欲しいなら、かなり相性が良いです。

upgrading-expo スキルの使い方

upgrading-expo のインストール前提

AI 環境が Skills に対応しているなら、Expo の skills リポジトリをインストールし、そこから upgrading-expo を呼び出します。一般的なパターンは次のとおりです。

npx skills add https://github.com/expo/skills --skill upgrading-expo

ツールチェーン側で別の skill loader を使っている場合は、次のリポジトリパスを指定します。
plugins/expo/skills/upgrading-expo

最初に読むべきリポジトリ内ファイル

実用的な upgrading-expo usage をするなら、まず次の順で読むのがおすすめです。

1. SKILL.md
2. references/new-architecture.md
3. references/react-19.md
4. references/react-compiler.md
5. references/native-tabs.md
6. references/expo-av-to-audio.md
7. references/expo-av-to-video.md

この順番は、実際によく詰まりやすいポイントに対応しています。先にアーキテクチャと React まわり、そのあとで機能単位の移行を見る流れです。

まずは upgrading-expo の基本アップグレード手順を試す

このスキルのベースラインとなるアップグレード手順は短く、深いデバッグに入る前にまず実行する価値があります。

npx expo install expo@latest
npx expo install --fix
npx expo-doctor
npx expo export -p ios --clear
rm -rf node_modules .expo
watchman watch-del-all

これが重要な理由:

• expo@latest で SDK の軸をそろえられる
• --fix で Expo 管理下のパッケージバージョンの不整合を調整できる
• expo-doctor で互換性の問題を早い段階で発見できる
• キャッシュ削除により、Metro や native 側の古い状態がアップグレード不具合に見える状況を避けられる

Linux を使っている場合や Watchman を使っていない場合は、クリーンアップ部分を環境に合わせて読み替えてください。

preview リリースを使うべきタイミングを見極める

このスキルでは、@next 配下の .preview バージョンとして提供される Expo のベータビルドについても触れています。今後の SDK を先に検証したいときや、まだ stable に入っていない修正を試したいときに便利です。

npx expo install expo@next --fix

ただし、これは意図的に行うべきです。preview アップグレードは、pre-release を評価中という明確な理由がない限り、本番アプリの標準選択には向きません。

upgrading-expo に渡すべき情報をそろえる

良い upgrading-expo guide のプロンプトには、現在地と目標状態が入っています。少なくとも次は渡してください。

• 現在の Expo SDK バージョン
• パッケージマネージャー
• Expo Go を使っているか、development builds を使っているか
• prebuild を実行しているか
• 主要パッケージ: expo-router、expo-av、react-native-reanimated、custom native modules
• install・build・runtime の現在のエラー
• iOS / Android / web のどこで失敗しているか

この文脈がないと、どうしても出力は一般論寄りになります。

曖昧な依頼を強いプロンプトに変える

弱いプロンプト:

Upgrade my Expo app.

より良いプロンプト:

Use the upgrading-expo skill to move my app from Expo SDK 53 to 54. We use expo-router, expo-av, Reanimated, and development builds. After npx expo install --fix, expo-doctor reports dependency mismatches and our app fails on startup with video playback errors. Tell me the likely breaking changes, the commands to run in order, and the code areas I should inspect first.

この書き方が有効な理由:

• 移行元と移行先の SDK が明示されている
• リスクの高いパッケージが列挙されている
• 一般論ではなく、優先順位付きの出力を求めている

自分のアプリをリファレンスガイドに対応付ける

リポジトリ内の reference は、依存関係の構成に意識的に対応付けると最も役立ちます。

• expo-av を音声再生や録音に使っている → references/expo-av-to-audio.md
• expo-av を動画に使っている → references/expo-av-to-video.md
• SDK 55 に上げる予定で expo-router/unstable-native-tabs を使っている → references/native-tabs.md
• SDK 53+ や 54+ に入り、native modules を含む → references/new-architecture.md
• SDK 54 を使う → references/react-19.md と references/react-compiler.md の両方を確認

ここが、単にリポジトリを流し読みするよりも、このスキルを使う情報的なメリットが出るポイントです。

upgrading-expo で特に警戒すべきアップグレード領域

実務上、このスキルが繰り返し示している壊れやすい箇所は次のとおりです。

• SDK 更新後のパッケージバージョン不整合
• 古い native modules と New Architecture の非互換
• SDK 54+ における react-native-worklets を含む Reanimated 設定変更
• アプリやライブラリコードにおける React 19 の API 変更
• expo-av から expo-audio / expo-video への移行
• Native Tabs における router レベルの UI 変更

自分のアプリがこのどれかに当てはまるなら、一般的なアップグレード要約ではなく、対象を絞った移行チェックリストを出させるのが効果的です。

2 段階で進める upgrading-expo ワークフロー

おすすめの upgrading-expo usage パターンは次の 2 パスです。

1. バージョンと依存関係を元に、アップグレード計画を作ってもらう
2. コマンドを実行する
3. 出たエラーをそのまま返し、絞り込んだ対処計画を出してもらう

このスキルは、expo-doctor、TypeScript、Metro、native build の具体的な出力があると、構造化された切り分けがかなりしやすくなります。

スキルが示唆するリリースノート系の確認ポイント

このスキルの破壊的変更チェックリストは、実際のレビュー対象として次のような箇所を示しています。

• 削除された API
• 変更された import path
• prebuild が必要になる native module の変更
• camera・audio・video の退行
• navigation の退行

つまり、確認は package.json だけで終わりません。アプリを起動する前に、影響を受けそうな import やコンポーネントをコードベース全体で検索しておくべきです。

prebuild と native code を使う場合の注意点

アプリで custom native modules や config plugins を使っている場合でも、upgrading-expo skill は有用です。ただし、markdown の reference だけでは済まない追加作業が発生する前提で考えたほうがよいです。そうしたプロジェクトでは、スキルに次のように分けて整理させるのがおすすめです。

• JS のみで完結する移行作業
• prebuild の再生成が必要な作業
• native dependency の互換性確認

この切り分けをしておくと、アップグレード中の混乱が減ります。

upgrading-expo スキル FAQ

upgrading-expo は初心者にも向いていますか？

はい。すでに Expo プロジェクトを持っていて、基本的なプロジェクト情報を共有できるなら有効です。ただし、Expo 全体の入門チュートリアルではありません。あくまでアップグレードに特化したガイドなので、現在の SDK バージョン、エラー内容、主要依存関係を伝えたほうが初心者でも結果が良くなります。

upgrading-expo スキルの守備範囲はどこまでですか？

このスキルは、アップグレード計画、コマンドの順序、既知の移行ホットスポットの整理を支援します。一方で、リポジトリ全体を自動解析したり、あらゆるサードパーティ native library の互換性を保証したりはしません。深い native 側の破損については、個別パッケージのドキュメントや GitHub Issues を併用する必要があります。

LLM に単に Expo のアップグレードを頼むのと何が違いますか？

最大の違いはキュレーションです。upgrading-expo skill は、一般的なプロンプトだと見落としがちな Expo 固有の移行リファレンスへモデルを誘導します。特に expo-av、React 19、React Compiler、Native Tabs、New Architecture の挙動差まわりで差が出やすいです。

upgrading-expo を使わないほうがいいのはどんなときですか？

次のような場合は見送って構いません。

• 既存アプリの更新ではなく、新規の Expo アプリを作り始める段階
• 問題が SDK アップグレードと無関係
• 自動 codemod や CLI ベースの移行ツールが必要
• 主な詰まりどころが、独自の移行手順を持つ単一のサードパーティ native library

upgrading-expo は preview SDK にも対応していますか？

はい。ベータリリースは .preview サフィックスを使い、@next からインストールすることがスキル内で説明されています。今後の変更を試すには便利ですが、通常のアップグレードでは stable のほうが安全です。

upgrading-expo は managed workflow 専用ですか？

いいえ。managed と prebuild ベースの Expo アプリの両方で使えます。ただし、prebuild や custom native code を含む場合は、追加の手動互換性チェックが必要になる可能性が高くなります。

upgrading-expo スキルをより効果的に使うには

upgrading-expo ではバージョン差分を正確に伝える

いちばん効果が大きい改善はシンプルです。「Expo をアップグレードしたい」ではなく、「SDK X から SDK Y へ」と明示してください。特に SDK 53・54・55 をまたぐかどうかで、必要な移行アドバイスは大きく変わります。

回答を左右するパッケージ構成を含める

より良い upgrading-expo の結果を得るには、reference docs の分岐に関わるパッケージを含めてください。

• expo-av
• expo-router
• react-native-reanimated
• custom native modules
• expo-doctor で失敗している任意のパッケージ

これにより、一般的なチェックリストではなく、影響が出そうな箇所に寄せたガイドを返しやすくなります。

言い換えではなく実際の診断結果を貼る

悪い例:

build failed after upgrade

良い例:

npx expo-doctor says package versions are invalid, Metro reports unresolved import from expo-av, and iOS dev build fails after enabling New Architecture.

正確なログがあると、このスキルは依存関係のずれなのか、API 移行の問題なのかを切り分けやすくなります。

優先順位付きの出力を依頼する

おすすめの依頼フォーマットは次の 4 点です。

1. 今すぐ実行すべきコマンド
2. 起こりやすい順の破損候補
3. 検索すべき files / imports
4. 修正後の確認手順

この形にすると、upgrading-expo guide の内容を時間がない状況でも実行しやすくなります。

インストール失敗とコード移行を分けて扱う

よくある失敗は、パッケージ install の問題と、ソースコード上の API 変更を一緒にしてしまうことです。スキルには次の順で処理させるとよいです。

• dependency の整合
• doctor の出力確認
• cache リセット
• source migration
• runtime verification

こうしておくと、堂々巡りのデバッグになりにくくなります。

コードベース向けの検索パターンを要求する

upgrading-expo skill の出力を実務に落とし込みやすくする最良の方法のひとつが、grep 形式の検索対象を出させることです。例:

Using the upgrading-expo skill, list the import paths, component names, and hooks I should search for to migrate from expo-av and to verify Native Tabs changes in SDK 55.

これにより、広い説明を具体的なコードレビュー作業へ変換できます。

1 回目の移行後に危険箇所を重点確認する

最初のアップグレード試行のあと、特に次を確認してください。

• 音声再生と録音
• 動画再生
• タブナビゲーション
• Expo Go と dev build それぞれでの起動
• 重いアニメーションや native modules を使う画面

これらは、このスキルが扱う SDK 移行問題が表面化しやすい領域です。

2 回目以降は upgrading-expo への質問範囲を絞る

アップグレード全体を毎回まとめて解決させようとしないでください。2 回目以降のプロンプトは範囲を絞るほうが有効です。

• “Focus only on React 19 changes in my shared UI package”
• “Focus only on expo-av video migration”
• “Focus only on New Architecture incompatibilities”

対象を狭くすると、対処手順はより明確で、精度も上がりやすくなります。