frontend-dev-guidelines

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

目的

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

このスキルを使用するタイミング

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

---

クイックスタート

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

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

• TypeScript で React.FC<Props> パターンを使用する
• 重いコンポーネントは遅延読み込みする: React.lazy(() => import())
• 読み込み状態のために <SuspenseLoader> でラップする
• データ取得には useSuspenseQuery を使用する
• インポートエイリアス: @/、~types、~components、~features を使用する
• スタイル: 100 行未満ならインライン、100 行超なら別ファイルにする
• 子コンポーネントに渡すイベントハンドラーには useCallback を使用する
• 末尾でデフォルトエクスポートする
• ローディングスピナーを使った早期 return はしない
• ユーザーへの通知には 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 & Lazy Loading
import React, { useState, useCallback, useMemo } from 'react';
const Heavy = React.lazy(() => import('./Heavy'));

// MUI Components
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';

// Project Components
import { SuspenseLoader } from '~components/SuspenseLoader';

// Hooks
import { useAuth } from '@/hooks/useAuth';
import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';

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

---

トピックガイド

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

モダンな React コンポーネントでは次を使用します:

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

主要な概念:

• 重いコンポーネント（DataGrid、チャート、エディター）は遅延読み込みする
• 遅延読み込みするコンポーネントは必ず Suspense でラップする
• SuspenseLoader コンポーネントを使用する（フェードアニメーション付き）
• コンポーネントの構造: Props → Hooks → Handlers → Render → Export

📖 完全ガイド: 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/ と components/ の違い:

• features/: ドメイン固有のもの（posts、comments、auth）
• components/: 真に再利用可能なもの（SuspenseLoader、CustomAppBar）

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

features/
  my-feature/
    api/          # API service layer
    components/   # Feature components
    hooks/        # Custom hooks
    helpers/      # Utility functions
    types/        # TypeScript types

📖 完全ガイド: 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 syntax
<Grid xs={12} md={6}>             // ❌ Old syntax

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

---

🛣️ ルーティング

TanStack Router - フォルダーベース:

• ディレクトリ: routes/my-route/index.tsx
• コンポーネントの遅延読み込み
• createFileRoute を使用
• パンくずリストのデータは loader で取得

例:

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

---

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

重要ルール: 早期リターンを使用しない

// ❌ NEVER - Causes layout shift
if (isLoading) {
    return <LoadingSpinner />;
}

// ✅ ALWAYS - Consistent layout
<SuspenseLoader>
    <Content />
</SuspenseLoader>

理由: Cumulative Layout Shift (CLS) を防ぎ、UX を向上させるため

エラーハンドリング:

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

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

---

⚡ パフォーマンス

最適化パターン:

• useMemo: 負荷の高い計算処理（filter、sort、map）
• useCallback: 子コンポーネントに渡すイベントハンドラー
• React.memo: 負荷の高いコンポーネント
• 検索のデバウンス（300〜500ms）
• メモリリーク防止（useEffect 内でのクリーンアップ）

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

---

📘 TypeScript

標準:

• strict モードを有効にし、any 型は使用しない
• 関数には戻り値の型を明示する
• 型のインポート: import type { User } from '~types/user'
• コンポーネントの props インターフェースには JSDoc を付ける

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

---

🔧 共通パターン

対象トピック:

• React Hook Form と Zod によるバリデーション
• 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 service
      components/
        MyFeature.tsx         # Main component
        SubComponent.tsx      # Related components
      hooks/
        useMyFeature.ts       # Custom hooks
        useSuspenseMyFeature.ts  # Suspense hooks
      helpers/
        myFeatureHelpers.ts   # Utilities
      types/
        index.ts              # TypeScript types
      index.ts                # Public exports

  components/
    SuspenseLoader/
      SuspenseLoader.tsx      # Reusable loader
    CustomAppBar/
      CustomAppBar.tsx        # Reusable app bar

  routes/
    my-route/
      index.tsx               # Route component
      create/
        index.tsx             # Nested route

---

モダンなコンポーネントのテンプレート（すぐにコピー可能）

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 }}>
                {/* Content */}
            </Paper>
        </Box>
    );
};

export default MyComponent;

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

---

関連スキル

• error-tracking: Sentry によるエラートラッキング（フロントエンドにも適用）
• backend-dev-guidelines: フロントエンドが利用するバックエンド API のパターン

---

スキルの状態: コンテキストを最適に管理するため、段階的読み込みに対応したモジュール構造