Frontend Conventions
Konventionen zur Erstellung guten und konsistenten Codes in der Next.js 16 + React 19 + TanStack Query v5 + FSD-Architektur.
Wann dieses Skill verwendet werden sollte
- Bei der Erstellung einer neuen Entity, Feature oder Widget
- Bei der Implementierung von CRUD-Formularen oder Datentabellen
- Bei der Refaktorierung vorhandenen Codes
- Bei der Überprüfung des Projekts auf Einhaltung der Konventionen
- Bei der Anwendung von API-Layer, State Management und Error-Handling-Patterns
Tech Stack
- Next.js 16.1.6 (App Router) + React 19.2.3 + TypeScript 5.9.2
- @tanstack/react-query ^5 + @tanstack/react-table ^8.21.3
- react-hook-form ^7.71.2 + zod ^3.25.76
- nuqs ^2.8.9 (URL-Status)
- Tailwind CSS ^4 + shadcn/ui (radix-nova) + sonner ^2.0.7 (Toast)
- Turborepo ^2.8.12 + pnpm 9.0+ (intern:
@workspace/ui,@workspace/api)
Regelkategorien
11 Kategorien, 67 Regeln. Je nach Aufgabe die entsprechende Datei referenzieren:
| Bereich | Datei | Wann referenzieren |
|---|---|---|
| Architektur | rules/architecture.md | FSD-Layer, Importrichtung, Entity-Slice, Barrel-Export |
| Next.js Patterns | rules/nextjs-patterns.md | Page Thin Shell, Providers, 'use client', spezielle Dateien |
| Code-Qualität | rules/code-quality.md | Dynamic Import, Conditional Render, Early Return, forwardRef |
| Queries | rules/queries.md | queryOptions-Factory, Query-Keys, staleTime, Prefetch, useQueries |
| Mutationen | rules/mutations.md | invalidate, useApiMutation, optimistisch |
| API-Layer | rules/api-layer.md | API-Objekt, Antworttypen, SSR Prefetch |
| Formulare | rules/forms.md | Zod-Schema, useForm, FormDialog, Edit-Pattern |
| Tabellen | rules/tables.md | DataTable, columns, serverseitige Paginierung |
| State Management | rules/state-management.md | nuqs, useState, Verbot globaler Zustände |
| Fehlerbehandlung | rules/error-handling.md | ApiError, Toast, Error Boundary |
| Namensgebung | rules/naming.md | Datei-/Hook-/Typ-/Konstanten-Namensgebung |
Den vollständigen Index finden Sie in INDEX.md.
Schweregrade
Jede Regel ist einem von drei Strengegraden zugeordnet:
| Stufe | Bedeutung | AI-Verhalten |
|---|---|---|
| 🚫 MUSS | Darf niemals verletzt werden | Immer diesem Pattern folgen |
| ⚠️ SOLLTE | Grundsätzlich befolgen, außer es gibt triftige Gründe | Standardmäßig anwenden; Ausnahmen mit Kommentar begründen |
| ✅ KANN | Empfohlen, aber flexibel | Nach Situation entscheiden |
Validierungs-Workflow
Bei Anfrage "Überprüfe dieses Projekt auf die Konventionen" in folgender Reihenfolge vorgehen:
- Tech-Stack prüfen — Next.js/React/TanStack-Query-Versionen in package.json überprüfen
- FSD-Struktur prüfen (PS-01~05) — Vorhandensein von apps/*/entities, features, widgets, shared prüfen
- Importrichtung validieren (PS-02) — Suchen, ob entity modules features/widgets importieren
- Entity-Vollständigkeit (PS-03) — Existenz von api.ts, queries.ts, hooks.ts, types.ts, index.ts in jeder Entity prüfen
- Mutations-Pattern (DF-06, DF-07) — Nutzungsrate von useApiMutation, Verstöße gegen rohes useMutation suchen
- Formular-Pattern (FM-01~07) — Paketierung des Zod-Schemas, useForm+zodResolver, Extraktion von Form-Hooks prüfen
- Tabellen-Pattern (TB-01~05) — Instanziierung von useReactTable, serverseitiger manueller Modus prüfen
- State Management (SM-01) — Verwendung von Context/zustand prüfen (verboten)
- Dateinamen-Konventionen (NM-01) — Einhaltung von kebab-case prüfen
Ausgabeformat:
- Verstöße (Regel-ID +
Datei:Zeile+ Änderungsvorschlag) - Zusammenfassung der Compliance (nach Kategorie)
- Priorisierte Empfehlungen (🚫 zuerst, ⚠️ danach)
Quick Start nach Aufgabe
Neue Entity hinzufügen: architecture → api-layer → queries → mutations → naming CRUD-Formular implementieren: forms → mutations (DF-06, DF-07) → naming Tabellenseite implementieren: tables → state-management → queries Neue Seite/Route hinzufügen: nextjs-patterns → architecture (PS-02, PS-05) Fehlerbehandlung: error-handling Performance-Optimierung: code-quality → queries (DF-10~12) Vorhandenen Code refaktorieren: Regeldateien des entsprechenden Bereichs vollständig
Referenzen
- Anthropic Best Practices zur Skill-Erstellung: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
- TanStack Query v5 Doku: https://tanstack.com/query/latest
- Feature-Sliced Design: https://feature-sliced.design