mobile-framework-expo

Expo 開発パターン

クイックガイド： Expo を使って本番環境に対応した React Native アプリを構築します。ほとんどのプロジェクトでは、Continuous Native Generation を使ったマネージドワークフロー、ファイルベースのナビゲーションを実現する Expo Router、ビルドや更新に使う EAS を利用します。本番環境のテストでは、Expo Go の代わりに開発ビルドを使用します。

---

<critical_requirements>

重要：このスキルを使用する前に

すべてのコードはプロジェクトの CLAUDE.md に記載された規約（kebab-case、名前付きエクスポート、インポート順序、import type、名前付き定数）に従う必要があります。

（本番環境のテストには、必ず開発ビルドを使用してください。Expo Go はプロトタイプ作成専用です）

（OTA 更新のクラッシュを防ぐため、ネイティブ依存関係を変更する際は必ず runtimeVersion を更新してください）

（ネイティブのカスタマイズには必ず設定プラグインを使用してください。マネージドワークフローでは android/ios ディレクトリを手動で編集しないでください）

（クライアント側の環境変数には必ず EXPO_PUBLIC_ プレフィックスを使用してください。これらの変数にシークレットを保存しないでください）

</critical_requirements>

---

自動検出： Expo、expo-router、EAS Build、EAS Update、expo-dev-client、app.config.js、app.json、expo prebuild、npx expo、eas.json、expo-constants、expo-notifications、Continuous Native Generation、CNG

使用する場面：

• 迅速な開発が必要な新しい React Native プロジェクトを開始するとき
• OTA（無線）更新が必要なアプリを構築するとき
• 設定より規約を重視したファイルベースのルーティングを使用するとき
• android/ios ディレクトリを維持せずにネイティブコードを管理するとき
• クラウドビルドでアプリストアにデプロイするとき

対象となる主なパターン：

• Continuous Native Generation（CNG）を使ったマネージドワークフロー
• Expo Router のファイルベースのナビゲーション
• EAS Build、Submit、Update のワークフロー
• 開発ビルドと Expo Go の使い分け
• ネイティブをカスタマイズする設定プラグイン
• 環境設定とシークレット
• プッシュ通知の設定

使用しない場面：

• Expo Modules API の範囲を超える複雑なカスタムネイティブコードが必要なアプリ
• アプリのサイズを 15MB 未満にする必要がある場合（Expo により容量が増加します）
• まだ移行の準備ができていないレガシー React Native プロジェクト

---

考え方

Expo は React Native 開発を「一度書けば、どこでもデバッグ」から「一度書けば、自信を持ってデプロイ」へと変えます。重要なポイントは、ほとんどのアプリではネイティブへの直接アクセスは不要であり、必要なのは API が一貫した、適切に保守されたネイティブモジュールだということです。

基本原則：

1. デフォルトはマネージド - Expo にネイティブの複雑さを任せ、必要な場合にのみ prebuild を実行します
2. Continuous Native Generation - android/ios はソースコードではなく、ビルド成果物として扱います
3. 実態を把握するには開発ビルド - Expo Go は学習用です。開発ビルドなら本番環境の実態を確認できます
4. 迅速な開発には OTA - アプリストアでの待ち時間なしに JavaScript の更新を配信します
5. Eject ではなく設定プラグイン - 必要に応じて、宣言的な方法でネイティブコードをカスタマイズします

メンタルモデル：

Expo は React Native の制約ではなく、プロフェッショナル向けの抽象化レイヤーです。Expo Modules API または prebuild を介していつでもネイティブコードに移行できますが、ほとんどのアプリではその必要はありません。

---

コアパターン

パターン 1：app.config.ts による動的設定

環境ごとのビルドには app.config.ts を使用します。SDK のバージョンとビルド番号には名前付き定数を使用します。

// app.config.ts - Environment-aware config
const IS_PRODUCTION = process.env.APP_ENV === "production";
const BUILD_NUMBER = 1;

export default ({ config }: ConfigContext): ExpoConfig => ({
  ...config,
  name: IS_PRODUCTION ? "MyApp" : "MyApp (Dev)",
  ios: {
    bundleIdentifier: IS_PRODUCTION ? "com.app" : "com.app.dev",
    buildNumber: String(BUILD_NUMBER),
  },
  android: {
    package: IS_PRODUCTION ? "com.app" : "com.app.dev",
    versionCode: BUILD_NUMBER,
  },
});

詳しい例：examples/core.md - アプリ設定のセクション

---

パターン 2：ネイティブのカスタマイズに設定プラグインを使用する

ネイティブコードを宣言的に変更します。変更は expo prebuild --clean の実行後も保持されます。権限、SDK バージョン、ネイティブ設定には設定プラグインを使用します。

// app.config.ts plugins array
plugins: [
  [
    "expo-camera",
    { cameraPermission: "Allow $(PRODUCT_NAME) to access your camera." },
  ],
  [
    "expo-build-properties",
    { android: { minSdkVersion: 24 }, ios: { deploymentTarget: "15.1" } },
  ],
];

詳しい例：examples/core.md - 設定プラグインのセクション

---

パターン 3：環境変数

クライアント側の変数には EXPO_PUBLIC_ プレフィックスを使用します。Metro ではプロパティへの直接アクセスが必要です。分割代入とブラケット記法は使用できません。

// MUST use direct access - Metro static analysis requirement
const API_URL = process.env.EXPO_PUBLIC_API_URL; // Works
// const { EXPO_PUBLIC_API_URL } = process.env;  // BROKEN - undefined at runtime

詳しい例：examples/core.md - 環境変数のセクション

---

パターン 4：開発ビルド

本番環境に近いテストには expo-dev-client を使用してください。Expo Go はプロトタイピング専用です。ネイティブ依存関係、プッシュ通知、正確なスプラッシュ画面には対応していません。

# Cloud build
eas build --profile development --platform ios
# Local build
npx expo run:ios

設定の詳細：examples/eas.md - 開発ビルドのセクション

---

パターン 5：アセット管理

フォントの読み込み中はスプラッシュ画面を表示したままにし、ぼかしハッシュのプレースホルダーとディスクキャッシュを使って、リモート画像には expo-image を使用してください。

SplashScreen.preventAutoHideAsync();
// Load fonts, then call SplashScreen.hideAsync() when ready

詳しい例：examples/core.md - フォントの読み込みと画像処理のセクション

---

<red_flags>

危険な兆候

• 本番テストに Expo Go を使用する -- ネイティブモジュール、プッシュ通知、正確なスプラッシュ画面に対応していません。必ず開発ビルドを使用してください。
• ネイティブの変更後に runtimeVersion を更新しない -- 互換性のないネイティブコードを含むアプリでは、OTA アップデートによってクラッシュが発生します。自動検出のために "fingerprint" ポリシーを使用してください。
• EXPO_PUBLIC_ 変数にシークレットを保存する -- JavaScript バンドルに埋め込まれ、逆コンパイルすれば誰でも確認できます。EAS Secrets とバックエンドプロキシを使用してください。
• android/ios ディレクトリを手動で編集する -- expo prebuild --clean を実行すると変更が失われます。設定プラグインを使用してください。
• process.env を分割代入する -- Metro では直接プロパティにアクセスする必要があります（process.env.EXPO_PUBLIC_*）。分割代入やブラケット記法では undefined が返されます。
• expo-av を使用する -- SDK 55 で削除されました。expo-video と expo-audio に移行してください。
• レガシーアーキテクチャを使用する -- SDK 54 の後に削除されました。React Native 0.82 以降では新アーキテクチャが必要です。

アンチパターンと注意事項の詳細：reference.md

</red_flags>

---

詳細なリソース：

• examples/core.md - プロジェクト設定、環境変数、フォント、画像
• examples/router.md - ファイルベースのルーティング、タブ、認証フロー、モーダル
• examples/eas.md - クラウドビルド、アプリストアへの提出、OTA アップデート
• reference.md - 判断フレームワーク、SDK との互換性、アンチパターン

---

<critical_reminders>

重要な注意事項

すべてのコードは、プロジェクトの CLAUDE.md に記載された規約に従う必要があります

（本番テストには開発ビルドを必ず使用してください。Expo Go はプロトタイピング専用です）

（OTA アップデートによるクラッシュを防ぐため、ネイティブ依存関係を変更した場合は必ず runtimeVersion を更新してください）

（ネイティブのカスタマイズには必ず設定プラグインを使用してください。管理ワークフローで android/ios ディレクトリを手動編集することは絶対に避けてください）

（クライアント側の環境変数には必ず EXPO_PUBLIC_ プレフィックスを使用してください。これらの変数にシークレットを保存することは絶対に避けてください）

これらのルールに従わないと、OTA アップデートによるクラッシュ、ビルドの破損、セキュリティ上の脆弱性が発生します。

</critical_reminders>