02. Expoプロジェクトを作成して実機で起動する

Spec Kitによる開発の司令塔（SPEC.md, DESIGN.md, CLAUDE.md）が整ったら、次はExpoのプロジェクト本体を作成します。

バイブコーディングにおいて最も興奮する瞬間のひとつが、「自分がこれから作るアプリが、手元のスマートフォンの画面に初めて映し出される瞬間」です。

PCの画面上でコードを眺めているだけでは、文字の大きさ、ボタンの押しやすさ、スクロールの心地よさは分かりません。手元の実機で動かしながら開発することこそが、モバイルアプリ開発で挫折しない最大の秘訣です。

この記事では、最新のExpo CLIとExpo Routerに対応した公式テンプレートを使ってプロジェクトを初期化し、スマホ実機（Expo Go / Expo Orbit）で即座にプレビュー表示するまでの手順を詳しく解説します。

1. Expo CLIと公式テンプレートの選び方

現在、Expoの開発標準は大きく進化しており、以下の特徴を持つモダンスタックが標準化されています。

Expo Router (File-based routing): Next.jsのApp Routerのように、フォルダとファイルを配置するだけで自動的に画面遷移が構成される仕組み。
TypeScript標準装備: 厳格な型推論により、AIエージェントがタイポやプロパティの不整合を自律的に検知・修正できる。
New Architecture対応: React 18+の並行レンダリングやネイティブ高速化に対応。

公式推奨の create-expo-app コマンドを使用すれば、最新の推奨構成がワンコマンドで手に入ります。

2. create-expo-appでプロジェクトを生成する

ターミナルを開き、先ほど作成した作業ディレクトリ内で以下のコマンドを実行します。

# 既存の作業ディレクトリ内で最新のExpoアプリを展開
npx create-expo-app@latest . --template default

インストールが進行し、必要なnpmパッケージのダウンロードが完了すると、package.json や設定ファイルが一式生成されます。

初期依存関係の確認

プロジェクトが正しく初期化されたか、Expo SDK・React Native・Routerのバージョンと依存関係を確認します。npx expo --version はCLIのバージョンで、SDKのバージョンとは別です。

npm ls expo react-native expo-router
npx expo-doctor

3. 生成されたディレクトリ構成の完全解説（Expo Router）

以下は本ガイドで使う構成例です。テンプレートの版によって app/ が src/app/ に置かれることがあります。以降の例は生成された構成に読み替え、app/ と src/app/ を併存させないでください。

habit-flow/
├── app/                  # 【最重要】Expo Routerの画面ファイル群
│   ├── (tabs)/           # タブナビゲーションの各画面
│   │   ├── index.tsx     # ホーム画面（タブ1）
│   │   ├── explore.tsx   # 探索画面（タブ2）
│   │   └── _layout.tsx   # タブバーの見た目・アイコン設定
│   ├── +not-found.tsx    # 存在しないURLを踏んだ時の404画面
│   └── _layout.tsx       # アプリ全体の最上位レイアウト（Provider等）
├── assets/               # アプリアイコンやスプラッシュ画像
│   ├── images/
│   └── fonts/
├── components/           # 再利用可能なUIコンポーネント
├── constants/            # アプリ共通のカラーパレット・テーマ定数
├── hooks/                # カスタムReactフック
├── app.json              # アプリの戸籍（名前・識別子・アイコン設定）
├── tsconfig.json         # TypeScript設定
├── package.json          # パッケージ定義
├── SPEC.md               # [Phase02] アプリ企画書
├── DESIGN.md             # [Phase03] デザイン仕様書
└── CLAUDE.md             # AIエージェントへの行動規範

AIエージェントはこの app/ フォルダの構成を見ながら、画面の追加やルーティングの変更を行っていきます。

4. 実機スマートフォン（Expo Go）で起動する手順

手順1：スマホに「Expo Go」をインストールする

iPhoneなら App Store、Androidなら Google Play から、無料の 「Expo Go」 アプリをインストールします。

手順2：開発サーバー（Metro Bundler）を起動する

プロジェクトのルートディレクトリで以下のコマンドを実行します。

npx expo start

ターミナル上に大きな QRコード がアスキーアートで表示されます。

Starting project at /Users/sangraal/habit-flow
Metro waiting on exp://192.168.1.15:8081

› Scan the QR code above with Expo Go (Android) or the Camera app (iOS)

› Press a │ open Android emulator
› Press i │ open iOS simulator
› Press w │ open web
› Press r │ reload app
› Press m │ toggle dev menu

手順3：スマホでスキャンする

iPhoneの場合: 標準の「カメラ」アプリを開き、PC画面上のQRコードにかざします。「Expo Goで開く」という通知バナーをタップします。
Androidの場合: 「Expo Go」アプリを開き、「Scan QR code」ボタンをタップしてターミナルのQRコードを読み取ります。

数秒のJavaScriptバンドル処理の後、あなたのスマートフォンの画面にテンプレートのウェルカム画面が表示されます！

5. シミュレータ / エミュレータとの併用テクニック

手元に実機がない場合や、PCの画面だけでサクサク確認したい場合は、PC内の仮想端末（シミュレータ）を使うことも可能です。

Macをお使いの場合 (iOS Simulator):
- Xcodeがインストールされている環境で、ターミナルで i キーを押すと、自動的にiPhoneのシミュレータが起動してアプリが開きます。
Windows / Mac (Android Emulator):
- Android Studioがインストールされている環境で、ターミナルで a キーを押すと、Android Virtual Device (AVD) が起動します。

実機とシミュレータを同時に起動しておくことも可能で、両方の画面がリアルタイムに同時に更新されます。

6. 初期起動時によくあるトラブルシューティング完全版

実機接続で初心者がつまずきやすいトラブルと、その解決手順をまとめました。

症状	主な原因	具体的な解決策
QRコードを読んでも画面が白いまま進まない	PCとスマホが別々のWi-Fiに繋がっている	PCとスマホを同じWi-Fiアクセスポイント（同じSSID）に接続してください。特に「5GHz帯」と「2.4GHz帯」で別ネットワーク扱いになるルーターに注意。
接続タイムアウト（Could not connect）になる	マンションWi-Fi等のプライバシーセパレータ機能	ルーターの機器間通信が遮断されている場合、トンネル接続モード（`npx expo start --tunnel`）を使ってください。Expoのクラウドを経由して接続できます。
ポート競合エラー（Port 8081 already in use）	別のプロセスがポートを使用中	自分が起動したMetroなら元のターミナルで停止するか、`npx expo start --port 8082` で別ポートを使います。`--clear` はキャッシュ削除であり、ポート競合は解消しません。
「Network response timed out」と出る	PCのローカルIPが切り替わった	ターミナルで `Ctrl + C` で一度停止し、Wi-Fiの接続を確認してから再起動してください。

7. まとめと次のステップ

実機に最初の画面が表示されたことで、アプリ開発の実行環境が完璧に整いました！手元で実機を触りながら、AIに指示を出してコードがリアルタイムに書き換わる「ホットリロード」の快感を味わう準備が完了です。

次の記事では、SPEC.md と DESIGN.md をAIエージェントに読み込ませ、アプリの画面骨格とタブ遷移を一気に自動生成する「03. Spec Kitでアプリの画面骨格とルーティングを生成する」に進みましょう。