フロントエンド開発ガイドライン

目的

モダン React 開発の包括的なガイド。Suspense ベースのデータ取得、遅延読み込み、適切なファイル構成、パフォーマンス最適化を重視しています。

このスキルを使う場合

• 新しいコンポーネントやページを作成する
• 新機能を構築する
• TanStack Query でデータを取得する
• TanStack Router でルーティングを設定する
• MUI v7 でコンポーネントをスタイリングする
• パフォーマンス最適化
• フロントエンドコードを整理する
• TypeScript のベストプラクティス

---

クイックスタート

新しいコンポーネントのチェックリスト

コンポーネントを作成しますか？このチェックリストに従ってください：

• React.FC<Props> パターンを TypeScript で使用する
• 重いコンポーネントは遅延読み込みする：React.lazy(() => import())
• <SuspenseLoader> でラップしてローディング状態を処理する
• データ取得には useSuspenseQuery を使用する
• インポートエイリアスを使用する：@/、~types、~components、~features
• スタイル：100 行以下はインライン、100 行以上は別ファイル
• 子に渡すイベントハンドラーに useCallback を使用する
• デフォルトエクスポートを下部に配置する
• ローディングスピナーで早期リターンしない
• ユーザー通知には useMuiSnackbar を使用する

新機能のチェックリスト

機能を作成しますか？この構造をセットアップしてください：

• features/{feature-name}/ ディレクトリを作成する
• サブディレクトリを作成する：api/、components/、hooks/、helpers/、types/
• API サービスファイルを作成する：api/{feature}Api.ts
• types/ で TypeScript 型をセットアップする
• routes/{feature-name}/index.tsx にルートを作成する
• 機能コンポーネントを遅延読み込みする
• Suspense の境界を使用する
• 機能 index.ts からパブリック API をエクスポートする

---

インポートエイリアスクイックリファレンス

エイリアス	解決先	例
@/	src/	import { apiClient } from '@/lib/apiClient'
~types	src/types	import type { User } from '~types/user'
~components	src/components	import { SuspenseLoader } from '~components/SuspenseLoader'
~features	src/features	import { authApi } from '~features/auth'

定義先：vite.config.ts の 180～185 行目

---

よく使うインポートのチートシート

// React & 遅延読み込み
import React, { useState, useCallback, useMemo } from 'react';
const Heavy = React.lazy(() => import('./Heavy'));

// MUI コンポーネント
import { Box, Paper, Typography, Button, Grid } from '@mui/material';
import type { SxProps, Theme } from '@mui/material';

// TanStack Query (Suspense)
import { useSuspenseQuery, useQueryClient } from '@tanstack/react-query';

// TanStack Router
import { createFileRoute } from '@tanstack/react-router';

// プロジェクトコンポーネント
import { SuspenseLoader } from '~components/SuspenseLoader';

// フック
import { useAuth } from '@/hooks/useAuth';
import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';

// 型
import type { Post } from '~types/post';

---

トピックガイド

🎨 コンポーネントパターン

モダン React コンポーネントは以下を使用します：

• 型安全性のための React.FC<Props>
• コード分割のための React.lazy()
• ローディング状態のための SuspenseLoader
• 名前付き const と デフォルトエクスポートのパターン

重要な概念：

• 重いコンポーネント（DataGrid、チャート、エディター）を遅延読み込みする
• 遅延読み込みするコンポーネントは常に Suspense でラップする
• SuspenseLoader コンポーネント（フェードアニメーション付き）を使用する
• コンポーネント構造：Props → フック → ハンドラー → レンダリング → エクスポート

📖 完全ガイド：resources/component-patterns.md

---

📊 データ取得

プライマリパターン：useSuspenseQuery

• Suspense の境界と共に使用する
• キャッシュファーストの戦略（API の前にグリッドキャッシュをチェック）
• isLoading チェックの置き換え
• ジェネリクスで型安全

API サービスレイヤー：

• features/{feature}/api/{feature}Api.ts を作成する
• apiClient axios インスタンスを使用する
• 機能ごとに一元化されたメソッド
• ルート形式：/form/route（/api/form/route ではない）

📖 完全ガイド：resources/data-fetching.md

---

📁 ファイル構成

features/ vs components/：

• features/：ドメイン固有（posts、comments、auth）
• components/：本当に再利用可能（SuspenseLoader、CustomAppBar）

機能のサブディレクトリ：

features/
  my-feature/
    api/          # API サービスレイヤー
    components/   # 機能コンポーネント
    hooks/        # カスタムフック
    helpers/      # ユーティリティ関数
    types/        # TypeScript 型

📖 完全ガイド：resources/file-organization.md

---

🎨 スタイリング

インラインと別ファイル：

• 100 行以下：インライン const styles: Record<string, SxProps<Theme>>
• 100 行以上：別の .styles.ts ファイル

プライマリメソッド：

• MUI コンポーネントに sx プロップを使用する
• SxProps<Theme> で型安全
• テーマアクセス：(theme) => theme.palette.primary.main

MUI v7 Grid：

<Grid size={{ xs: 12, md: 6 }}>  // ✅ v7 構文
<Grid xs={12} md={6}>             // ❌ 古い構文

📖 完全ガイド：resources/styling-guide.md

---

🛣️ ルーティング

TanStack Router - フォルダベース：

• ディレクトリ：routes/my-route/index.tsx
• コンポーネントを遅延読み込みする
• createFileRoute を使用する
• ローダーにブレッドクラムデータを含める

例：

import { createFileRoute } from '@tanstack/react-router';
import { lazy } from 'react';

const MyPage = lazy(() => import('@/features/my-feature/components/MyPage'));

export const Route = createFileRoute('/my-route/')({
    component: MyPage,
    loader: () => ({ crumb: 'My Route' }),
});

📖 完全ガイド：resources/routing-guide.md

---

⏳ ローディング・エラー状態

重要なルール：早期リターンをしない

// ❌ 決してしない - レイアウトのずれを引き起こす
if (isLoading) {
    return <LoadingSpinner />;
}

// ✅ 常にこうする - 一貫したレイアウト
<SuspenseLoader>
    <Content />
</SuspenseLoader>

理由： Cumulative Layout Shift（CLS）を防止、UX の向上

エラーハンドリング：

• ユーザーフィードバックに useMuiSnackbar を使用する
• react-toastify は決して使用しない
• TanStack Query の onError コールバック

📖 完全ガイド：resources/loading-and-error-states.md

---

⚡ パフォーマンス

最適化パターン：

• useMemo：高価な計算（フィルター、ソート、マップ）
• useCallback：子に渡すイベントハンドラー
• React.memo：高価なコンポーネント
• デバウンス検索（300～500ms）
• メモリリーク防止（useEffect でのクリーンアップ）

📖 完全ガイド：resources/performance.md

---

📘 TypeScript

標準：

• strict モード、any 型なし
• 関数の明示的な戻り値の型
• 型インポート：import type { User } from '~types/user'
• JSDoc 付きコンポーネントプロップインターフェース

📖 完全ガイド：resources/typescript-standards.md

---

🔧 よく使うパターン

カバーされたトピック：

• Zod 検証付き React Hook Form
• DataGrid ラッパーコントラクト
• ダイアログコンポーネント標準
• 現在のユーザーの useAuth フック
• キャッシュ無効化を含むミューテーションパターン

📖 完全ガイド：resources/common-patterns.md

---

📚 完全な例

実装済みの完全な例：

• すべてのパターン付きのモダンコンポーネント
• 完全な機能構造
• API サービスレイヤー
• 遅延読み込み付きルート
• Suspense + useSuspenseQuery
• 検証付きフォーム

📖 完全ガイド：resources/complete-examples.md

---

ナビゲーションガイド

必要な場合	このリソースを読む
コンポーネントを作成する	component-patterns.md
データを取得する	data-fetching.md
ファイル・フォルダを整理する	file-organization.md
コンポーネントをスタイリングする	styling-guide.md
ルーティングを設定する	routing-guide.md
ローディング・エラーを処理する	loading-and-error-states.md
パフォーマンスを最適化する	performance.md
TypeScript 型	typescript-standards.md
フォーム・認証・DataGrid	common-patterns.md
完全な例を見る	complete-examples.md

---

コア原則

1. 重いものはすべて遅延読み込みする：ルート、DataGrid、チャート、エディター
2. ローディングに Suspense を使用する：早期リターンではなく SuspenseLoader を使用
3. useSuspenseQuery：新規コードのプライマリデータ取得パターン
4. 機能は整理されている：api/、components/、hooks/、helpers/ のサブディレクトリ
5. スタイルはサイズベース：100 行以下はインライン、100 行以上は別ファイル
6. インポートエイリアスを使用する：@/、~types、~components、~features
7. 早期リターンをしない：レイアウトのずれを防止
8. useMuiSnackbar：すべてのユーザー通知用

---

クイックリファレンス：ファイル構造

src/
  features/
    my-feature/
      api/
        myFeatureApi.ts       # API サービス
      components/
        MyFeature.tsx         # メインコンポーネント
        SubComponent.tsx      # 関連コンポーネント
      hooks/
        useMyFeature.ts       # カスタムフック
        useSuspenseMyFeature.ts  # Suspense フック
      helpers/
        myFeatureHelpers.ts   # ユーティリティ
      types/
        index.ts              # TypeScript 型
      index.ts                # パブリックエクスポート

  components/
    SuspenseLoader/
      SuspenseLoader.tsx      # 再利用可能なローダー
    CustomAppBar/
      CustomAppBar.tsx        # 再利用可能なアプリバー

  routes/
    my-route/
      index.tsx               # ルートコンポーネント
      create/
        index.tsx             # ネストされたルート

---

モダンコンポーネントテンプレート（コピー用）

import React, { useState, useCallback } from 'react';
import { Box, Paper } from '@mui/material';
import { useSuspenseQuery } from '@tanstack/react-query';
import { featureApi } from '../api/featureApi';
import type { FeatureData } from '~types/feature';

interface MyComponentProps {
    id: number;
    onAction?: () => void;
}

export const MyComponent: React.FC<MyComponentProps> = ({ id, onAction }) => {
    const [state, setState] = useState<string>('');

    const { data } = useSuspenseQuery({
        queryKey: ['feature', id],
        queryFn: () => featureApi.getFeature(id),
    });

    const handleAction = useCallback(() => {
        setState('updated');
        onAction?.();
    }, [onAction]);

    return (
        <Box sx={{ p: 2 }}>
            <Paper sx={{ p: 3 }}>
                {/* コンテンツ */}
            </Paper>
        </Box>
    );
};

export default MyComponent;

完全な例は resources/complete-examples.md を参照してください

---

関連スキル

• error-tracking：Sentry を使用したエラートラッキング（フロントエンドにも適用）
• backend-dev-guidelines：フロントエンドが使用するバックエンド API パターン

---

スキル状態：最適なコンテキスト管理のための段階的読み込みを備えたモジュール構造