marnixGeerkens/rocketlauncher-claude-code

Frontend-Entwicklungsrichtlinien

Zweck

Umfassender Leitfaden für moderne React-Entwicklung mit Schwerpunkt auf Suspense-basiertem Datenabruf, Lazy Loading, korrekter Dateiorganisation und Performance-Optimierung.

Wann diese Skill verwenden

• Erstellen neuer Komponenten oder Seiten
• Aufbau neuer Features
• Datenabruf mit TanStack Query
• Einrichten des Routings mit TanStack Router
• Styling von Komponenten mit MUI v7
• Performance-Optimierung
• Organisieren von Frontend-Code
• TypeScript-Best Practices

---

Schnellstart

Checkliste für neue Komponenten

Eine Komponente erstellen? Folgen Sie dieser Checkliste:

• Verwenden Sie das React.FC<Props>-Pattern mit TypeScript
• Lazy laden, falls schwere Komponente: React.lazy(() => import())
• In <SuspenseLoader> für Ladezustände einwickeln
• useSuspenseQuery für Datenabruf verwenden
• Import-Aliase: @/, ~types, ~components, ~features
• Styles: Inline bei <100 Zeilen, separate Datei bei >100 Zeilen
• useCallback für Event-Handler, die an Kinder übergeben werden
• Standard-Export am Ende
• Keine frühen Returns mit Lade-Spinnern
• useMuiSnackbar für Benutzerbenachrichtigungen verwenden

Checkliste für neue Features

Ein Feature erstellen? Richten Sie diese Struktur ein:

• features/{feature-name}/-Verzeichnis erstellen
• Unterverzeichnisse erstellen: api/, components/, hooks/, helpers/, types/
• API-Service-Datei erstellen: api/{feature}Api.ts
• TypeScript-Typen in types/ einrichten
• Route in routes/{feature-name}/index.tsx erstellen
• Feature-Komponenten lazy laden
• Suspense-Grenzen verwenden
• Öffentliche API aus Feature-index.ts exportieren

---

Import-Alias-Referenz

Alias	Löst auf	Beispiel
@/	src/	import { apiClient } from '@/lib/apiClient'
~types	src/types	import type { User } from '~types/user'
~components	src/components	import { SuspenseLoader } from '~components/SuspenseLoader'
~features	src/features	import { authApi } from '~features/auth'

Definiert in: vite.config.ts Zeilen 180-185

---

Spickzettel für häufige Imports

// React & Lazy Loading
import React, { useState, useCallback, useMemo } from 'react';
const Heavy = React.lazy(() => import('./Heavy'));

// MUI-Komponenten
import { Box, Paper, Typography, Button, Grid } from '@mui/material';
import type { SxProps, Theme } from '@mui/material';

// TanStack Query (Suspense)
import { useSuspenseQuery, useQueryClient } from '@tanstack/react-query';

// TanStack Router
import { createFileRoute } from '@tanstack/react-router';

// Projekt-Komponenten
import { SuspenseLoader } from '~components/SuspenseLoader';

// Hooks
import { useAuth } from '@/hooks/useAuth';
import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';

// Typen
import type { Post } from '~types/post';

---

Themenführer

🎨 Komponenten-Patterns

Moderne React-Komponenten verwenden:

• React.FC<Props> für Typsicherheit
• React.lazy() für Code-Splitting
• SuspenseLoader für Ladezustände
• Benannte Konstante + Standard-Export-Pattern

Wichtige Konzepte:

• Schwere Komponenten lazy laden (DataGrid, Diagramme, Editoren)
• Lazy-Komponenten immer in Suspense einwickeln
• SuspenseLoader-Komponente verwenden (mit Einblend-Animation)
• Komponenten-Struktur: Props → Hooks → Handler → Rendern → Exportieren

📖 Vollständiger Leitfaden: resources/component-patterns.md

---

📊 Datenabruf

PRIMÄRES PATTERN: useSuspenseQuery

• Mit Suspense-Grenzen verwenden
• Cache-First-Strategie (Grid-Cache vor API prüfen)
• Ersetzt isLoading-Prüfungen
• Typsicher mit Generics

API-Service-Ebene:

• features/{feature}/api/{feature}Api.ts erstellen
• apiClient axios-Instanz verwenden
• Zentralisierte Methoden pro Feature
• Routenformat: /form/route (NICHT /api/form/route)

📖 Vollständiger Leitfaden: resources/data-fetching.md

---

📁 Dateiorganisation

features/ vs components/:

• features/: Domänenspezifisch (posts, comments, auth)
• components/: Wirklich wiederverwendbar (SuspenseLoader, CustomAppBar)

Feature-Unterverzeichnisse:

features/
  my-feature/
    api/          # API-Service-Ebene
    components/   # Feature-Komponenten
    hooks/        # Eigene Hooks
    helpers/      # Hilfsfunktionen
    types/        # TypeScript-Typen

📖 Vollständiger Leitfaden: resources/file-organization.md

---

🎨 Styling

Inline vs. getrennt:

• <100 Zeilen: Inline const styles: Record<string, SxProps<Theme>>

• 100 Zeilen: Separate .styles.ts-Datei

Primäre Methode:

• sx-Prop für MUI-Komponenten verwenden
• Typsicher mit SxProps<Theme>
• Theme-Zugriff: (theme) => theme.palette.primary.main

MUI v7 Grid:

<Grid size={{ xs: 12, md: 6 }}>  // ✅ v7-Syntax
<Grid xs={12} md={6}>             // ❌ Alte Syntax

📖 Vollständiger Leitfaden: resources/styling-guide.md

---

🛣️ Routing

TanStack Router - Ordnerbasiert:

• Verzeichnis: routes/my-route/index.tsx
• Komponenten lazy laden
• createFileRoute verwenden
• Breadcrumb-Daten im Loader

Beispiel:

import { createFileRoute } from '@tanstack/react-router';
import { lazy } from 'react';

const MyPage = lazy(() => import('@/features/my-feature/components/MyPage'));

export const Route = createFileRoute('/my-route/')({
    component: MyPage,
    loader: () => ({ crumb: 'My Route' }),
});

📖 Vollständiger Leitfaden: resources/routing-guide.md

---

⏳ Lade- und Fehlerzustände

KRITISCHE REGEL: Keine frühen Returns

// ❌ NIE - Verursacht Layout-Verschiebung
if (isLoading) {
    return <LoadingSpinner />;
}

// ✅ IMMER - Konsistentes Layout
<SuspenseLoader>
    <Content />
</SuspenseLoader>

Warum: Verhindert kumulative Layout-Verschiebung (CLS), bessere Benutzererfahrung

Fehlerbehandlung:

• useMuiSnackbar für Benutzerfeedback verwenden
• NIE react-toastify
• TanStack Query onError-Callbacks

📖 Vollständiger Leitfaden: resources/loading-and-error-states.md

---

⚡ Performance

Optimierungs-Patterns:

• useMemo: Teure Berechnungen (filtern, sortieren, mappen)
• useCallback: Event-Handler, die an Kinder übergeben werden
• React.memo: Teure Komponenten
• Debounced-Suche (300-500ms)
• Speicherleck-Prävention (Bereinigung in useEffect)

📖 Vollständiger Leitfaden: resources/performance.md

---

📘 TypeScript

Standards:

• Strenger Modus, kein any-Typ
• Explizite Rückgabetypen bei Funktionen
• Typ-Imports: import type { User } from '~types/user'
• Komponenten-Prop-Schnittstellen mit JSDoc

📖 Vollständiger Leitfaden: resources/typescript-standards.md

---

🔧 Häufige Patterns

Abgedeckte Themen:

• React Hook Form mit Zod-Validierung
• DataGrid-Wrapper-Verträge
• Dialog-Komponentenstandards
• useAuth-Hook für aktuellen Benutzer
• Mutations-Patterns mit Cache-Invalidierung

📖 Vollständiger Leitfaden: resources/common-patterns.md

---

📚 Vollständige Beispiele

Voll funktionsfähige Beispiele:

• Moderne Komponente mit allen Patterns
• Vollständige Feature-Struktur
• API-Service-Ebene
• Route mit Lazy Loading
• Suspense + useSuspenseQuery
• Formular mit Validierung

📖 Vollständiger Leitfaden: resources/complete-examples.md

---

Navigationsleitfaden

Bei Bedarf...	Diese Ressource lesen
Eine Komponente erstellen	component-patterns.md
Daten abrufen	data-fetching.md
Dateien/Ordner organisieren	file-organization.md
Komponenten stylen	styling-guide.md
Routing einrichten	routing-guide.md
Lade-/Fehlerzustände behandeln	loading-and-error-states.md
Performance optimieren	performance.md
TypeScript-Typen	typescript-standards.md
Formulare/Auth/DataGrid	common-patterns.md
Vollständige Beispiele sehen	complete-examples.md

---

Kernprinzipien

1. Alles Schwere lazy laden: Routen, DataGrid, Diagramme, Editoren
2. Suspense für Laden: SuspenseLoader verwenden, keine frühen Returns
3. useSuspenseQuery: Primäres Datenabruf-Pattern für neuen Code
4. Features sind organisiert: api/, components/, hooks/, helpers/-Unterverzeichnisse
5. Styles basierend auf Größe: <100 inline, >100 getrennt
6. Import-Aliase: @/, ~types, ~components, ~features verwenden
7. Keine frühen Returns: Verhindert Layout-Verschiebung
8. useMuiSnackbar: Für alle Benutzerbenachrichtigungen

---

Kurzreferenz: Dateistruktur

src/
  features/
    my-feature/
      api/
        myFeatureApi.ts       # API-Service
      components/
        MyFeature.tsx         # Hauptkomponente
        SubComponent.tsx      # Verwandte Komponenten
      hooks/
        useMyFeature.ts       # Eigene Hooks
        useSuspenseMyFeature.ts  # Suspense-Hooks
      helpers/
        myFeatureHelpers.ts   # Hilfsfunktionen
      types/
        index.ts              # TypeScript-Typen
      index.ts                # Öffentliche Exporte

  components/
    SuspenseLoader/
      SuspenseLoader.tsx      # Wiederverwendbarer Loader
    CustomAppBar/
      CustomAppBar.tsx        # Wiederverwendbare App-Leiste

  routes/
    my-route/
      index.tsx               # Routenkomponente
      create/
        index.tsx             # Verschachtelte Route

---

Moderne Komponentenvorlage (Schnellkopie)

import React, { useState, useCallback } from 'react';
import { Box, Paper } from '@mui/material';
import { useSuspenseQuery } from '@tanstack/react-query';
import { featureApi } from '../api/featureApi';
import type { FeatureData } from '~types/feature';

interface MyComponentProps {
    id: number;
    onAction?: () => void;
}

export const MyComponent: React.FC<MyComponentProps> = ({ id, onAction }) => {
    const [state, setState] = useState<string>('');

    const { data } = useSuspenseQuery({
        queryKey: ['feature', id],
        queryFn: () => featureApi.getFeature(id),
    });

    const handleAction = useCallback(() => {
        setState('updated');
        onAction?.();
    }, [onAction]);

    return (
        <Box sx={{ p: 2 }}>
            <Paper sx={{ p: 3 }}>
                {/* Inhalt */}
            </Paper>
        </Box>
    );
};

export default MyComponent;

Vollständige Beispiele finden Sie unter resources/complete-examples.md

---

Verwandte Skills

• error-tracking: Fehlerverfolgung mit Sentry (gilt auch für das Frontend)
• backend-dev-guidelines: Backend-API-Patterns, die das Frontend konsumiert

---

Skill-Status: Modulare Struktur mit progressiver Beladung für optimales Kontextmanagement