shinpr/frontend-technical-spec

技術設計ルール（フロントエンド）

技術スタックの基本方針

TypeScriptベースのReactアプリケーション実装。アーキテクチャパターンはプロジェクトの要件と規模に応じて選択する。

環境変数管理とセキュリティ

環境変数管理

• ビルドツールの環境変数システムを使用: process.envはブラウザ環境で動作しない
• 設定レイヤーを通じて環境変数を一元管理
• TypeScriptによる適切な型安全性の実装
• デフォルト値設定と必須チェックの適切な実装

// ビルドツールの環境変数（公開値のみ）
const config = {
  apiUrl: import.meta.env.API_URL || 'http://localhost:3000',
  appName: import.meta.env.APP_NAME || 'My App'
}

// フロントエンドでは動作しない
const apiUrl = process.env.API_URL // NG

セキュリティ（クライアントサイド制約）

• 重要: すべてのフロントエンドコードは公開され、ブラウザで見える
• クライアントサイドに秘密情報を保存しない: APIキー、トークン、シークレットを環境変数に含めない
• .envファイルをGitに含めない（バックエンドと同様）
• 機密情報のログ出力を禁止（パスワード、トークン、個人情報）
• エラーメッセージに機密情報を含めない

秘密情報の正しい取り扱い:

// セキュリティリスク: APIキーがブラウザで露出
const apiKey = import.meta.env.VITE_API_KEY
const response = await fetch(`https://api.example.com/data?key=${apiKey}`)

// 正しい: バックエンドが秘密情報を管理、フロントエンドはプロキシ経由でアクセス
const response = await fetch('/api/data') // バックエンドがAPIキー認証を処理

アーキテクチャ設計

フロントエンドアーキテクチャパターン

Reactコンポーネントアーキテクチャ:

• Function Components: 必須、class componentsは非推奨
• Custom Hooks: ロジック再利用と依存性注入のため
• コンポーネント階層: Atoms → Molecules → Organisms → Templates → Pages
• Props-driven: コンポーネントは必要なすべてのデータをPropsで受け取る
• Co-location: テスト、スタイル、関連ファイルをコンポーネントと同じ場所に配置

状態管理パターン:

• Local State: コンポーネント固有の状態にはuseState
• Context API: コンポーネントツリー全体で状態を共有（テーマ、認証等）
• Custom Hooks: 状態ロジックと副作用をカプセル化
• Server State: APIデータのキャッシュにはReact QueryまたはSWR

データフロー統一原則

クライアントサイドのデータフロー

Reactアプリケーション全体で一貫したデータフローを維持：

• Single Source of Truth: 各状態には1つの権威あるソースがある

  • UI状態: コンポーネントStateまたはContext
  • サーバーデータ: React Query/SWRでキャッシュされたAPIレスポンス
  • フォームデータ: React Hook Formを使ったControlled Components

• 単方向フロー: データはPropsを通じて上から下へ流れる

  APIレスポンス → State → Props → Render → UI
  ユーザー入力 → イベントハンドラ → State更新 → 再レンダリング
  

• Immutable Updates: State更新には不変パターンを使用

  // 不変なState更新
  setUsers(prev => [...prev, newUser])
  
  // 可変なState更新（禁止）
  users.push(newUser)
  setUsers(users)
  

データフローにおける型安全性

• Frontend → Backend: Props/State（型保証済み） → APIリクエスト（シリアライゼーション）
• Backend → Frontend: APIレスポンス（unknown） → 型ガード → State（型保証済み）

// 型安全なデータフロー
async function fetchUser(id: string): Promise<User> {
  const response = await fetch(`/api/users/${id}`)
  const data: unknown = await response.json()

  if (!isUser(data)) {
    throw new Error('Invalid user data')
  }

  return data // User型として保証
}

ビルドとテスト

package.jsonのpackageManagerフィールドに応じた実行コマンドを使用すること。

ビルドコマンド

• package.jsonから以下に該当するスクリプトを自動検出して実行:
  • 開発サーバー
  • 本番ビルド
  • 型チェック（出力なし）

テストコマンド

• test - テスト実行
• test:coverage - カバレッジ付きテスト実行
• test:coverage:fresh - カバレッジ付きテスト実行（キャッシュクリア）
• test:safe - 安全なテスト実行（自動クリーンアップ付き）
• cleanup:processes - Vitestプロセスのクリーンアップ

品質チェック要件

実装完了時に品質チェックは必須：

Phase 1-3: 基本チェック

• check - Biome（lint + format）
• build - TypeScriptビルド

Phase 4-5: テストと最終確認

• test - テスト実行
• test:coverage:fresh - カバレッジ測定
• check:all - 全体統合チェック

カバレッジ要件

• 必須: 単体テストのカバレッジは60%以上
• コンポーネント別目標:
  • Atoms: 70%以上
  • Molecules: 65%以上
  • Organisms: 60%以上
  • Custom Hooks: 65%以上
  • Utils: 70%以上

非機能要件

• ブラウザ互換性: Chrome/Firefox/Safari/Edge（最新2バージョン）
• レンダリング時間: 主要ページで5秒以内