frontend-technical-spec

# 技術設計ルール（フロントエンド） ## 前提条件の検出 ツールやフレームワークに固有のルールを適用する前に、`package.json`、ロックファイル、TypeScript・ビルド設定、CI定義、代表的なコンポーネントを確認する。React、Vite、Next.js、状態管理ライブラリ、フォームライブラリ、スクリプトは、リポジトリ内の根拠に明記されている場合にのみ利用可能として扱う。周辺のパターンから導いた結論には推測であることを明記する。不足している判断によってレンダリングアーキテクチャ、互換性、セキュリティ、検証方法が変わる場合は作業を止め、必要な根拠またはユーザー判断を具体的に示す。 ## 技術スタックの基本方針 リポジトリ設定からTypeScriptベースのReactアプリケーションであることを確認できる場合に、このルールを適用する。現行要件と制約を、コンポーネントの責務、状態の所有者、サーバー/クライアント境界、観測可能な検証点へ対応づけてアーキテクチャを選択する。 ## 環境変数管理とセキュリティ ### 環境変数管理 - **ビルドツールのクライアント公開機構を使用**: ブラウザコードが読めるのは設定済みのbundler/frameworkによって明示的に公開された値だけとし、サーバー専用の環境アクセスはクライアントバンドルの��側に置く - 設定レイヤーを通じて環境変数を一元管理 - 公開値は、アプリケ��ションで使用する前に1つの型付き設定境界でパースする - 要件で未設定時の有効な振る舞いが定義されている場合にのみデフォルト値を設ける。それ以外は、変数名と期待する形式を示して起動時またはビルド時の検証を失敗させる ```typescript // ビルドツールの環境変数（公開値のみ。クライアント公開変数は VITE_ 接頭辞が必要） const config = { apiUrl: import.meta.env.VITE_API_URL || 'http://localhost:3000', appName: import.meta.env.VITE_APP_NAME || 'My App' } // フロントエンドでは動作しない const apiUrl = process.env.API_URL // NG ``` ### セキュリティ（クライアントサイド制約） - **重要**: すべてのフロントエンドコードは公開され、ブラウザで見える - **シークレットはサーバー側に置く**: クライアントへ公開する設定には公開値だけを含め、APIキー、トークン、認証情報はバックエンドまたは信頼できるサービスが所有する - ローカルの`.env`ファイルはバージョン管理の対象外とし、必要な変数名はシークレットを含まないサンプルファイルで示す - 現在の信頼境界で許可されたフィールドだけをログおよびレスポンスに含める。パスワード、トークン、個人データは除去する **秘密情報の正しい取り扱い**: ```typescript // セキュリティリスク: APIキーがブラウザで露出 const apiKey = import.meta.env.VITE_API_KEY const response = await fetch(`https://api.example.com/data?key=${apiKey}`) // 正しい: バックエンドが秘密情報を管理、フロントエンドはプロキシ経由でアクセス ...