Expoが「Welcome to Expo」画面でスタックする問題の解決法

問題の説明

Expo SDK51以降でアプリを起動すると、以下の状態が発生します：

• appディレクトリに正しいファイルが存在しているにも関わらず
• 常に「Welcome to Expo」画面が表示される
• クリーン起動(expo start --clear)や再起動での解決不可
• 「appディレクトリにファイルを作成」というプロンプトが表示されるが無意味

この状態はアプリが正しく初期化されておらず、実質的に開発が不能になります。

根本原因

主な原因は互換性のないBabel設定です：

• react-native-dotenvなどのサードパーティBabelプラグイン
• カスタム設定がExpo Routerの環境変数を上書きする
• 結果としてExpoがデフォルト画面を強制表示

公式ドキュメントでも言及されている既知の問題：

“react-native-dotenv is not compatible with expo-router... you'll see the empty state Welcome to Expo screen.”
Expo SDK 51 Changelog

解決手順

ステップ1: 競合するパッケージの削除

1. 該当パッケージをアンインストール：

npm uninstall react-native-dotenv babel-plugin-transform-inline-environment-variables

2. babel.config.jsの編集：

module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'] // 他プラグインは全て削除
  };
};

カスタムBabel設定が不要な場合はbabel.config.jsごと完全削除が効果的な場合も：

rm babel.config.js

SDK51+はデフォルト設定を含むため、ファイル自体が不要になるケースがあります。

ステップ2: キャッシュのクリア

npx expo start --clear  # 開発サーバーのキャッシュ削除

# プラットフォーム別ビルドキャッシュクリア
npx expo run:android --clean
npx expo run:ios --clean

ステップ3: 環境変数の移行（必要な場合）

SDK51+ではEXPO_PUBLIC_プレフィックスで直接アクセス可能：

EXPO_PUBLIC_API_KEY=your_api_key_here

アプリ内での使用方法：

const apiKey = process.env.EXPO_PUBLIC_API_KEY;

解決後の確認ポイント

1. プロジェクトの警告を解消：

   npx expo-doctor

2. パッケージのアップグレード：

   npx expo install --fix

3. TypeScript使用時は型定義を更新：

   declare global {
     namespace NodeJS {
       interface ProcessEnv {
         EXPO_PUBLIC_API_KEY: string;
       }
     }
   }

再発防止策

• 環境変数は公式ガイドに沿ってExpo Environment Variablesを参照
• Babelカスタマイズは最小限に
• アップグレード時はExpo Upgrade Guideを必ず確認

本番ビルド前にexpo prebuildで設定検証すると潜在的問題を早期発見できます。