expo-project-structure

Expo プロジェクト構成

フォルダー構成がまだコミットされていない、新規 Expo アプリ用の初期スケルトンです。

新規プロジェクトにのみ適用してください。 アプリにすでにレイアウトがある場合は、既存の規約に従い、ファイルはそのままの場所に置いてください。これは開始時のデフォルトであり、適用を強制したり、移行先にしたりする標準ではありません。プロジェクトが新規かどうか判断できない場合は、何かを移動する前に確認してください。

以下のルールに基づいて構成した全体のレイアウトです。

├── assets/
├── scripts/
├── src/
│   ├── app/                       # Expo Router routes ONLY — every file is a route
│   │   ├── api/                   #   server API routes, grouped here
│   │   │   ├── user+api.ts
│   │   │   └── settings+api.ts
│   │   ├── _layout.tsx
│   │   ├── _layout.web.tsx         #   platform-specific layout
│   │   ├── index.tsx
│   │   └── settings.tsx
│   ├── components/                 # reusable UI: button, card, table…
│   │   ├── table/                  #   complex component → folder + index.tsx
│   │   │   ├── cell.tsx
│   │   │   └── index.tsx
│   │   ├── bar-chart.tsx
│   │   ├── bar-chart.web.tsx        #   platform-specific variant
│   │   └── button.tsx
│   ├── screens/                    # screen bodies that route files render
│   │   ├── home/
│   │   │   ├── card.tsx            #   used only by Home — not shared
│   │   │   └── index.tsx           #   rendered by src/app/index.tsx
│   │   └── settings.tsx
│   ├── server/                     # server-only helpers used by app/api
│   │   ├── auth.ts
│   │   └── db.ts
│   ├── utils/                      # standalone helpers + colocated tests
│   │   ├── format-date.ts
│   │   └── format-date.test.ts
│   ├── hooks/                      # reusable hooks: use-theme.ts…
│   ├── constants.ts
│   └── theme.ts
├── app.json
├── eas.json
└── package.json

src/ と src/app

設定ファイルと分けるため、アプリのコードは src/ 配下に置きます。Expo Router は標準で app/ と src/app/ の両方に対応しています。切り替えるには、フォルダーを移動してバンドラーを再起動します。デフォルトテンプレートでは、tsconfig.json で @/* を ./src/* にエイリアス設定しています。

src/app はルート専用です。ここにあるすべてのファイルがルートになるため、それ以外のものは置けません。以下のものはすべて、隣接するフォルダーに配置します。

components/ — 再利用可能な UI

ボタン、カード、テーブルなど、汎用的で再利用する UI を置きます。それぞれのファイルで、名前付きエクスポートを 1 つだけ定義します。ファイル名には、デフォルトの create-expo-app テンプレートに合わせてケバブケース（bar-chart.tsx）を使います。コンポーネントが大きくなったら、専用フォルダーを作成し、ルートを index.tsx に置いて、プライベートなサブコンポーネントを隣にまとめて配置します。インポートパス（@/components/table）は変わりません。

screens/ — 画面本体

app/ のファイルはルートでなければならないため、再利用しない複雑な画面 UI を置く場所はそこにはありません。画面が大きくなり、個別のコンポーネントに分割する必要が出てきたら、screens/ に置き、各ルートからその画面をレンダリングするだけにします。

import { Home } from "@/screens/home";

export default function HomeScreen() {
  // route-specific concerns only — e.g. read url params here
  return <Home />;
}

画面専用のコンポーネントは、そのフォルダー内（screens/home/components/）にまとめて配置します。さらに、同じ画面を複数のルートでレンダリングできます。

server/ + app/api/ — サーバーコードの分離

app/ 内のファイルに +api を付けると、サーバーのAPI ルートになります。サーバーコードはフロントエンドコードとは異なり、Node のようなサーバー環境で実行されます（EAS Hosting またはサードパーティーサービスにデプロイ）。また、シークレット環境変数（EXPO_PUBLIC_* だけでなく process.env.X）を読み取れます。分けて配置してください。

• すべてのルートを app/api/ 配下にまとめます → /api/user、/api/settings。これにより、ルートをまとめられ、衝突（たとえば /user 画面と /user ルート）を避けられます。
• サーバー専用の共通ヘルパーは src/server/ に置きます。
• +api ファイルと server/ をフロントエンド専用のチェックから除外する ESLint ルールを検討してください。

プラットフォーム固有のコード

小さな違いには Platform.select / Platform.OS を使います。大きな違いには、インラインの if/else ではなく、プラットフォーム別のファイルに分けます。たとえば、bar-chart.tsx + bar-chart.web.tsx のようにし、拡張子を省略してインポート（@/components/bar-chart）します。Metro がターゲットに応じて適切なファイルを選択します。

• すべてのバリエーションで Props は同一でなければなりません。
• プラットフォーム拡張子のないデフォルトファイルが常に必要です。コンポーネントが単一プラットフォーム用の場合は、何もしない実装にします。
• 対応する拡張子：.ios、.android、.native、.web

スタイルとテストをまとめて配置する

• スタイル： StyleSheet.create({ ... }) オブジェクトは別の .styles ファイルに分けず、コンポーネントファイルの末尾に置きます。
• テスト： format-date.test.ts は format-date.ts の隣に置きます（独立した __tests__/ フォルダーより推奨）。これにより、テスト対象のファイルがひと目でわかります。

AI と設定ファイル

エージェント向けの指示はリポジトリのルート（AGENTS.md / CLAUDE.md）に置き、プロジェクトのスキルは .claude/ 配下に置きます。その他の設定ファイルとアセットは src/ の外に置きます。app.json / app.config.ts、eas.json、package.json、assets/、scripts/ などです。

---

Kadi Kraman によるExpo アプリのフォルダー構成のベストプラクティスに基づいています。src/ の優先順位とエイリアスの仕組みについては、Expo のドキュメントを参照してください。

フィードバックの送信

このスキルでエラーや誤解を招く情報、古い情報を見つけた場合は、Expo が改善できるよう報告してください。

npx --yes @expo/agent-cli@latest feedback --category skills --subject "expo-project-structure" "<actionable feedback>"

具体的で実行可能な報告内容がある場合にのみ送信してください。関連するコンテキストをできるだけ詳しく含めてください。 エージェントが Expo のタスクに繰り返し失敗する場合や、ユーザーが介入しなければならない場合は、タスクの内容、期待される結果、問題点を簡潔に報告し、--category evals と、関連する Expo パッケージまたはコマンドを --subject として指定してください。