フロントエンド TypeScript 型定義スキル
目的: frontend/types/index.ts の既存パターンに従ったTypeScript型定義を作成するためのガイダンス。
概要
すべてのTypeScript型は frontend/types/index.ts で定義されています。型はバックエンドAPIのレスポンス構造と一致し、フロントエンドアプリケーション全体で型安全性を提供します。
frontend/types/index.ts の型パターン
1. ユーザー型
export interface User {
id: string;
email: string;
name: string;
createdAt?: string;
updatedAt?: string;
}
export interface UserCredentials {
email: string;
password: string;
}
export interface UserSignupData extends UserCredentials {
name: string;
}
パターン:
- オブジェクト型には
interfaceを使用 - オプションフィールドには
?を付与 - 型の継承には
extendsを使用 - フロントエンドの型にはキャメルケースを使用(バックエンドがスネークケースでも)
2. タスク型
export type TaskStatus = "pending" | "completed";
export type TaskPriority = "low" | "medium" | "high";
export interface Task {
id: number;
user_id: string;
title: string;
description?: string;
completed: boolean;
priority: TaskPriority;
due_date?: string;
tags: string[];
created_at: string;
updated_at: string;
}
export interface TaskFormData {
title: string;
description?: string;
priority?: TaskPriority;
due_date?: string;
tags?: string[];
}
export interface TaskQueryParams {
status?: "all" | "pending" | "completed";
sort?: "created" | "title" | "updated" | "priority" | "due_date";
search?: string;
page?: number;
limit?: number;
}
パターン:
- ユニオン型(文字列リテラル)には
typeを使用 - オブジェクト型には
interfaceを使用 - バックエンドのフィールド名と一致させる(APIフィールドにはスネークケース例:
user_id、due_date、created_at) - フォームデータ用に個別の型を作成(必須フィールド以外はすべてオプション)
- クエリパラメータ用に個別の型を作成(すべてオプション)
3. APIレスポンス型
export interface ApiResponse<T = unknown> {
data?: T;
success: boolean;
message?: string;
error?: {
code: string;
message: string;
details?: unknown;
};
}
export interface PaginatedResponse<T> {
data: T[];
meta: {
total: number;
page: number;
limit: number;
totalPages: number;
};
}
パターン:
- 再利用可能な構造にはジェネリック型
<T>を使用 - デフォルト型パラメータを指定(
<T = unknown>) successブール値フラグを含める- オプションの
data、message、errorフィールドを含める - ページネーション対応レスポンス用に個別の型を作成(
metaオブジェクトを含む)
4. 認証型
export interface AuthResponse {
success: boolean;
token: string;
user: User;
}
export interface Session {
user: User;
token: string;
expiresAt: number;
}
パターン:
successブール値を含めるtoken文字列を含めるuserオブジェクト(User型)を含める- セッションに
expiresAtタイムスタンプを含める
5. エラー型
export interface AppError {
message: string;
code?: string;
statusCode?: number;
field?: string;
}
export interface FormErrors {
[key: string]: string | undefined;
}
パターン:
- エラーオブジェクトには
interfaceを使用 - オプションフィールドには
?を付与 - 動的なオブジェクト型(FormErrors)にはインデックスシグネチャ
[key: string]を使用
6. UI型
export type LoadingState = "idle" | "loading" | "success" | "error";
export type ToastType = "success" | "error" | "warning" | "info";
export interface ToastMessage {
id: string;
type: ToastType;
message: string;
duration?: number;
}
パターン:
- ユニオン型(文字列リテラル)には
typeを使用 - オブジェクト型には
interfaceを使用 - 一意な識別のために
idを含める - オプションフィールドには
?を付与
7. エクスポート/インポート型
export type ExportFormat = "csv" | "json";
export interface ImportResult {
imported: number;
errors: number;
errorDetails?: string[];
}
パターン:
- ユニオン型(文字列リテラル)には
typeを使用 - 結果オブジェクトには
interfaceを使用 - 成功/エラー追跡用にカウントを含める
- オプションのエラー詳細配列を含める
型命名規則
インターフェース
- パスカルケース:
User、Task、ApiResponse - 説明的な名前:
TaskFormData、UserSignupData
型(ユニオン型)
- パスカルケース:
TaskStatus、TaskPriority、LoadingState - 説明的な名前:
ToastType、ExportFormat
Props型
- コンポーネント名 + Props:
TaskItemProps、ProtectedRouteProps - 例:
interface TaskItemProps { task: Task; }
フォームデータ型
- エンティティ名 + FormData:
TaskFormData、UserSignupData - 例:
interface TaskFormData { title: string; description?: string; }
クエリパラメータ型
- エンティティ名 + QueryParams:
TaskQueryParams - 例:
interface TaskQueryParams { status?: "all" | "pending" | "completed"; }
バックエンドスキーマとの一致
フィールド名マッピング
バックエンド(スネークケース) → フロントエンド(フォームデータはキャメルケース、APIレスポンスはスネークケース)
// バックエンドAPIレスポンス(バックエンドと完全一致)
export interface Task {
id: number;
user_id: string; // バックエンドからのスネークケース
title: string;
due_date?: string; // バックエンドからのスネークケース
created_at: string; // バックエンドからのスネークケース
updated_at: string; // バックエンドからのスネークケース
}
// フロントエンドフォームデータ(使いやすさのためキャメルケース)
export interface TaskFormData {
title: string;
dueDate?: string; // フロントエンド用キャメルケース
tags?: string[];
}
パターン:
- APIレスポンス型はバックエンドと完全一致(スネークケース)
- フォームデータ型はフロントエンドでの使いやすさのためキャメルケースを使用
- APIとの送受信時に形式を変換する
必須フィールドとオプションフィールド
// バックエンドAPIレスポンス(バックエンドからのすべてのフィールド)
export interface Task {
id: number; // 必須(バックエンドから)
user_id: string; // 必須(バックエンドから)
title: string; // 必須(バックエンドから)
description?: string; // オプション(バックエンドから)
completed: boolean; // 必須(バックエンドから)
priority: TaskPriority; // 必須(バックエンドから)
due_date?: string; // オプション(バックエンドから)
tags: string[]; // 必須(バックエンドから、空配列可)
created_at: string; // 必須(バックエンドから)
updated_at: string; // 必須(バックエンドから)
}
// フロントエンドフォームデータ(ユーザーが編集できるフィールドのみ)
export interface TaskFormData {
title: string; // 必須(ユーザーが提供必須)
description?: string; // オプション
priority?: TaskPriority; // オプション(デフォルトあり)
due_date?: string; // オプション
tags?: string[]; // オプション(空配列可)
}
パターン:
- APIレスポンス型はバックエンドからのすべてのフィールドを含める
- フォームデータ型はユーザーが編集できるフィールドのみを含める
- オプションフィールドには
?を付与 - 必須フィールドには
?を付与しない
型構造パターン
1. オブジェクトには interface を使用
export interface User {
id: string;
email: string;
}
使用する場合: プロパティを持つオブジェクト型
2. ユニオン、インターセクション、またはエイリアスには type を使用
export type TaskStatus = "pending" | "completed";
export type TaskPriority = "low" | "medium" | "high";
使用する場合: ユニオン型、インターセクション、または型エイリアス
3. 再利用可能な構造にはジェネリック型を使用
export interface ApiResponse<T = unknown> {
data?: T;
success: boolean;
}
使用する場合: 異なる型で動作する再利用可能な構造
4. オプションプロパティには ? を付与
export interface Task {
title: string; // 必須
description?: string; // オプション
}
使用する場合: 存在しない可能性のあるフィールド
新しい型追加の完全な例
ステップ 1: エンティティ型の定義(バックエンドと一致)
export interface Category {
id: number;
user_id: string;
name: string;
color?: string;
created_at: string;
updated_at: string;
}
ステップ 2: フォームデータ型の定義(ユーザー入力用)
export interface CategoryFormData {
name: string;
color?: string;
}
ステップ 3: クエリパラメータ型の定義(APIクエリ用)
export interface CategoryQueryParams {
search?: string;
page?: number;
limit?: number;
}
ステップ 4: APIクライアントで使用
async getCategories(
userId: string,
queryParams?: CategoryQueryParams
): Promise<ApiResponse<PaginatedResponse<Category>>> {
// 実装
}
憲法要件
- FR-030: すべてのAPI呼び出しに対する型付きTypeScriptインターフェース ✅
- FR-037: TypeScript strict モード ✅
参考資料
- 仕様:
specs/002-frontend-todo-app/spec.md- エンティティ定義 - 計画:
specs/002-frontend-todo-app/plan.md- 型付きAPIコントラクト - 型ファイル:
frontend/types/index.ts- 完全な型定義
共通パターンまとめ
- ✅ オブジェクト型には
interfaceを使用 - ✅ ユニオン型(文字列リテラル)には
typeを使用 - ✅ 再利用可能な構造にはジェネリック型
<T>を使用 - ✅ オプションフィールドには
?を付与 - ✅ バックエンドのフィールド名と一致させる(APIレスポンスはスネークケース)
- ✅ フォームデータ型にはキャメルケースを使用
- ✅ フォームデータとクエリパラメータ用に個別の型を作成
- ✅ 説明的な名前を使用(EntityFormData、EntityQueryParams)
- ✅ バックエンドからのすべての必須フィールドを含める
- ✅ ジェネリックのデフォルト型パラメータを指定(
<T = unknown>)