Frontend TypeScript Types Skill
Zweck: Anleitung zur Erstellung von TypeScript-Typdefinitionen nach den bestehenden Mustern aus frontend/types/index.ts.
Überblick
Alle TypeScript-Typen sind in frontend/types/index.ts definiert. Die Typen entsprechen der Backend-API-Antwortstruktur und gewährleisten Typsicherheit in der gesamten Frontend-Anwendung.
Typmuster aus frontend/types/index.ts
1. Benutzertypen
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;
}
Muster:
- Verwende
interfacefür Objekttypen - Markiere optionale Felder mit
? - Verwende
extendsfür Typvererbung - Verwende camelCase für Frontend-Typen (auch wenn das Backend snake_case verwendet)
2. Aufgabentypen
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;
}
Muster:
- Verwende
typefür Union-Typen (String-Literale) - Verwende
interfacefür Objekttypen - Stimme mit Backend-Feldnamen überein (snake_case für API-Felder wie
user_id,due_date,created_at) - Erstelle separate Typen für Formulardaten (alle optional außer Pflichtfeldern)
- Erstelle separate Typen für Abfrageparameter (alle optional)
3. API-Antworttypen
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;
};
}
Muster:
- Verwende generische Typen
<T>für wiederverwendbare Strukturen - Gib einen Standard-Typ-Parameter an (
<T = unknown>) - Füge ein
success-Boolean-Flag hinzu - Füge optionale Felder
data,messageunderrorhinzu - Erstelle einen separaten Typ für paginierte Antworten mit dem
meta-Objekt
4. Authentifizierungstypen
export interface AuthResponse {
success: boolean;
token: string;
user: User;
}
export interface Session {
user: User;
token: string;
expiresAt: number;
}
Muster:
- Füge ein
success-Boolean hinzu - Füge einen
token-String hinzu - Füge ein
user-Objekt (User-Typ) hinzu - Füge einen
expiresAt-Zeitstempel für die Sitzung hinzu
5. Fehlertypen
export interface AppError {
message: string;
code?: string;
statusCode?: number;
field?: string;
}
export interface FormErrors {
[key: string]: string | undefined;
}
Muster:
- Verwende
interfacefür Fehlerobjekte - Markiere optionale Felder mit
? - Verwende die Index-Signatur
[key: string]für dynamische Objekttypen (FormErrors)
6. UI-Typen
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;
}
Muster:
- Verwende
typefür Union-Typen (String-Literale) - Verwende
interfacefür Objekttypen - Füge eine eindeutige
idzur Identifikation hinzu - Markiere optionale Felder mit
?
7. Export-/Importtypen
export type ExportFormat = "csv" | "json";
export interface ImportResult {
imported: number;
errors: number;
errorDetails?: string[];
}
Muster:
- Verwende
typefür Union-Typen (String-Literale) - Verwende
interfacefür Ergebnisobjekte - Füge Zähler für Erfolg/Fehlerverfolgung hinzu
- Füge ein optionales Array mit Fehlerdetails hinzu
Namenskonventionen für Typen
Interfaces
- PascalCase:
User,Task,ApiResponse - Beschreibende Namen:
TaskFormData,UserSignupData
Typen (Union Types)
- PascalCase:
TaskStatus,TaskPriority,LoadingState - Beschreibende Namen:
ToastType,ExportFormat
Props-Typen
- Komponentenname + Props:
TaskItemProps,ProtectedRouteProps - Beispiel:
interface TaskItemProps { task: Task; }
Formulardatentypen
- Entitätsname + FormData:
TaskFormData,UserSignupData - Beispiel:
interface TaskFormData { title: string; description?: string; }
Abfrageparametertypen
- Entitätsname + QueryParams:
TaskQueryParams - Beispiel:
interface TaskQueryParams { status?: "all" | "pending" | "completed"; }
Übereinstimmung mit dem Backend-Schema
Feldnamen-Zuordnung
Backend (snake_case) → Frontend (camelCase für Formulardaten, snake_case für API-Antwort)
// Backend-API-Antwort (stimmt exakt mit Backend überein)
export interface Task {
id: number;
user_id: string; // snake_case vom Backend
title: string;
due_date?: string; // snake_case vom Backend
created_at: string; // snake_case vom Backend
updated_at: string; // snake_case vom Backend
}
// Frontend-Formulardaten (camelCase für einfachere Verwendung)
export interface TaskFormData {
title: string;
dueDate?: string; // camelCase für Frontend
tags?: string[];
}
Muster:
- API-Antworttypen stimmen exakt mit dem Backend überein (snake_case)
- Formulardatentypen verwenden camelCase für einfachere Frontend-Nutzung
- Konvertiere zwischen den Formaten beim Senden/Empfangen von der API
Erforderliche vs. optionale Felder
// Backend-API-Antwort (alle Felder vom Backend)
export interface Task {
id: number; // Erforderlich (vom Backend)
user_id: string; // Erforderlich (vom Backend)
title: string; // Erforderlich (vom Backend)
description?: string; // Optional (vom Backend)
completed: boolean; // Erforderlich (vom Backend)
priority: TaskPriority; // Erforderlich (vom Backend)
due_date?: string; // Optional (vom Backend)
tags: string[]; // Erforderlich (vom Backend, kann leeres Array sein)
created_at: string; // Erforderlich (vom Backend)
updated_at: string; // Erforderlich (vom Backend)
}
// Frontend-Formulardaten (nur Felder, die der Benutzer bearbeiten kann)
export interface TaskFormData {
title: string; // Erforderlich (Benutzer muss bereitstellen)
description?: string; // Optional
priority?: TaskPriority; // Optional (hat Standardwert)
due_date?: string; // Optional
tags?: string[]; // Optional (kann leeres Array sein)
}
Muster:
- API-Antworttypen enthalten alle Felder vom Backend
- Formulardatentypen enthalten nur Felder, die der Benutzer bearbeiten kann
- Markiere optionale Felder mit
? - Erforderliche Felder haben kein
?
Muster für Typstrukturen
1. Verwende interface für Objekte
export interface User {
id: string;
email: string;
}
Wann verwenden: Objekttypen mit Eigenschaften
2. Verwende type für Unions, Schnittmengen oder Aliasse
export type TaskStatus = "pending" | "completed";
export type TaskPriority = "low" | "medium" | "high";
Wann verwenden: Union-Typen, Schnittmengen oder Typ-Aliasse
3. Verwende generische Typen für wiederverwendbare Strukturen
export interface ApiResponse<T = unknown> {
data?: T;
success: boolean;
}
Wann verwenden: Wiederverwendbare Strukturen, die mit verschiedenen Typen arbeiten
4. Markiere optionale Eigenschaften mit ?
export interface Task {
title: string; // Erforderlich
description?: string; // Optional
}
Wann verwenden: Felder, die möglicherweise nicht existieren
Vollständiges Beispiel: Hinzufügen neuer Typen
Schritt 1: Entitätstyp definieren (entspricht Backend)
export interface Category {
id: number;
user_id: string;
name: string;
color?: string;
created_at: string;
updated_at: string;
}
Schritt 2: Formulardatentyp definieren (für Benutzereingaben)
export interface CategoryFormData {
name: string;
color?: string;
}
Schritt 3: Abfrageparametertyp definieren (für API-Abfragen)
export interface CategoryQueryParams {
search?: string;
page?: number;
limit?: number;
}
Schritt 4: Im API-Client verwenden
async getCategories(
userId: string,
queryParams?: CategoryQueryParams
): Promise<ApiResponse<PaginatedResponse<Category>>> {
// Implementierung
}
Verfassungsanforderungen
- FR-030: Typisierte TypeScript-Interfaces für alle API-Aufrufe ✅
- FR-037: TypeScript strict mode ✅
Referenzen
- Spezifikation:
specs/002-frontend-todo-app/spec.md- Entitätsdefinitionen - Plan:
specs/002-frontend-todo-app/plan.md- API-Verträge mit Typen - Typendatei:
frontend/types/index.ts- Vollständige Typdefinitionen
Zusammenfassung der gängigen Muster
- ✅ Verwende
interfacefür Objekttypen - ✅ Verwende
typefür Union-Typen (String-Literale) - ✅ Verwende generische Typen
<T>für wiederverwendbare Strukturen - ✅ Markiere optionale Felder mit
? - ✅ Stimme mit Backend-Feldnamen überein (snake_case für API-Antworten)
- ✅ Verwende camelCase für Formulardatentypen
- ✅ Erstelle separate Typen für Formulardaten und Abfrageparameter
- ✅ Verwende beschreibende Namen (EntityFormData, EntityQueryParams)
- ✅ Füge alle erforderlichen Felder vom Backend hinzu
- ✅ Gib Standard-Typ-Parameter für Generika an (
<T = unknown>)