frontend-dev-guidelines

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

目的

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

React 18 + TypeScript + MUI v7 + TanStack Router/Query 向けに作成されています。異なるスタックをお使いですか？原則を適宜応用してください。リポジトリのルートにある CLAUDE_INTEGRATION_GUIDE.md を参照してください。

このスキルを使う場面

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

---

クイックスタート

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

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

• TypeScript の React.FC<Props> パターンを使用する
• 大きなコンポーネントは遅延読み込みする：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 & 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/：ドメイン固有のもの（投稿、コメント、認証）
• 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 を使用します
• ローダーにパンくずリストのデータを含めます

例：

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>

理由： 累積レイアウトシフト（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 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 のパターン

---

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