react-frontend-spa

使用React实现和改进SPA前端的指南。在不依赖Next.js或服务器端功能的前提下，以React Router为中心进行客户端实现时使用。认证统一使用AuthProvider和useAuth自定义钩子，并从OpenAPI生成类型/客户端供使用（通过orval或openapi-typescript）。适用于采用ESLint+Prettier、zod、shadcn/ui以及设计令牌（CSS变量/Tailwind主题）的情况。目录结构采用直观命名如modules/components/hooks/providers/services等，以便能够应对复杂化。

React Frontend SPA

目的

ReactのSPAを、型安全・一貫性・保守性重視で構築するための実装指針を提供する。

基本方針

SSRやサーバーサイド機能に依存しない。ルーティングはReact Routerで完結させる。
TypeScriptを必須とし、strictを有効にする。
UIはshadcn/uiを基準にし、デザイントークンで一貫性を保つ。
バリデーションはzodを基本とする。
APIクライアントはOpenAPIから自動生成し、手書きの型定義は避ける。

参照ドキュメント

詳細は references に分離してある。必要に応じて読む。

references/structure.md ディレクトリ構成と依存ルール、modules指針
references/auth.md 認証（AuthProvider / useAuth / ProtectedRoute）
references/api-client.md OpenAPIクライアント生成（orval / openapi-typescript）
references/validation.md zodによるバリデーション方針
references/ui-design.md shadcn/ui とデザイントークン運用
references/quality.md ESLint/Prettier/型チェック

実装時の判断基準

迷ったら「生成コードに寄せる」「再利用はcomponents/hooksへ」「機能はmodulesへ」で整理する。
既存の命名や語彙に揃える。新規語彙は最小限にする。