Technologie-Stack-Analyse und Cursor-Regel-Generator

=================== --- description: globs: alwaysApply: true --- # Page UI Tech Stack & Dependencies Guide ## Projektübersicht **Page UI** ist eine Landing-Page-Komponentenbibliothek, die auf einem modernen React/Next.js-Stack basiert, mit: - **Website**: Next.js 14 Dokumentationsseite mit Komponentendemos - **CLI-Tool**: `@ page-ui/wizard` für einfache Projektinitialisierung - **Komponenten**: Copy-Paste-React-Komponenten, basierend auf Radix UI + Tailwind CSS ## Kern-Framework-Stack ### **Next.js 14.2.24** (App Router) - **Framework**: React-Meta-Framework mit App-Router-Architektur - **Verwendete Funktionen**: API-Routen, SSG/SSR, OG-Bildgenerierung, Bundle-Analyse - **Best Practice**: App-Router-Muster verwenden, pages-Verzeichnis vermeiden ### **React 18.2.0** - **UI-Bibliothek**: Kern-React-Bibliothek mit Concurrent-Funktionen - **Funktionen**: Suspense, automatisches Batching, Server-Komponenten - **Best Practice**: React-18-Muster verwenden ### **TypeScript 5.1.3** - **Konfiguration**: Strict-Modus für bessere Typsicherheit aktiviert - **Best Practice**: Moderne TS-Version ## UI-Komponentensystem ### **Radix UI Primitives** (v1.x-Serie) Vollständiges, barrierefreiheitsorientiertes Komponenten-Ökosystem: **Best Practices**: - Compound-Component-Muster verwenden - Immer mit Tailwind-Klassen anpassen, nicht mit Inline-Stilen - Korrekte ARIA-Attribute implementieren (eingebaut) - In benutzerdefinierte Komponenten für konsistentes Styling einbinden ### **Shadcn/UI-Designmuster** - **Ort**: `/components/shared/ui/`-Verzeichnis - **Philosophie**: Copy-Paste-Komponenten, keine NPM-Abhängigkeiten - **Styling**: Tailwind CSS + CSS-Variablen für Theming - **Varianten**: Verwendet `class-variance-authority` für typsichere Varianten ## Styling & Designsystem ### **Tailwind CSS 3.3.3** + Ökosystem ```json { "tailwindcss": "^3.3.3", "@ tailwindcss/forms": "^0.5.4", "@ tailwindcss/typography": "^0.5.9", "tailwindcss-animate": "^1.0.7", "tailwind-merge": "^1.14.0" } ``` **Best Practices**: - `tailwind-merge` für bedingte Klassen verwenden: `cn(baseClasses, conditionalClasses)` - CSS-Variablen für Theming nutzen: `hsl(var(--primary))` - Plugins für Formulare und Typografie verwenden - Konsistente Abstands- und Farbsysteme implementieren ### **Animationsbibliotheken** - **Framer Motion 10.16.4**: Komplexe Animationen, Seitenübergänge - **Tailwind Animate**: Einfache CSS-Animationen - **Best Practice**: CSS-Animationen für einfache Effekte, Framer Motion für komplexe Interaktionen ```typescript // Framer-Motion-Best-Practices: import { motion, AnimatePresence } from 'framer-motion' function AnimatedComponent() { return ( <motion.div initial={{ opacity: 0, y: 20 }} animate={{ opacity: 1, y: 0 }} exit={{ opacity: 0, y: -20 }} transition={{ duration: 0.3 }} > Inhalt </motion.div> ) } ``` ## State-Management & Formulare ### **Zustand 4.5.2** (Globaler State) - **Philosophie**: Minimales, unvoreingenommenes State-Management - **Verwendung**: Theme-Präferenzen, globaler UI-State, Komponenten-Playground-State - **Best Practice**: Typisierte Stores mit korrekten Selektoren erstellen ```typescript interface ThemeState { theme: 'light' | 'dark' setTheme: (theme: 'light' | 'dark') => void } export const useThemeStore = create<ThemeState>((set) => ({ theme: 'light', setTheme: (theme) => set({ theme }), })) ``` ### **React Hook Form 7.46.2** + Validierung - **Formularbibliothek**: Leistungsstarke, unkontrollierte Formulare - **Validierung**: `@ hookform/resolvers` ^3.3.1 + `zod` ^3.22.2 - **Integration**: Funktioniert nahtlos mit Radix-UI-Formularkomponenten ```typescript // Best-Practice-Formularsetup: const formSchema = z.object({ email: z.string().email(), name: z.string().min(2), }) function ContactForm() { const form = useForm<z.infer<typeof formSchema>>({ resolver: zodResolver(formSchema), }) return <form onSubmit={form.handleSubmit(onSubmit)}>...</form> } ``` ### **Zod 3.22.2** (Schema-Validierung) - **Verwendung**: Formularvalidierung, API-Antwortvalidierung, Typerzeugung - **Best Practice**: Schemas nahe der Verwendung definieren, Typinferenz nutzen ## Content-Management-System ### **Benutzerdefinierte Contentlayer-Implementierung** ```json { "@ shipixen/next-contentlayer-module": "1.0.2", "shipixen-contentlayer": "1.0.2", "@ shipixen/pliny": "1.0.13" } ``` **Funktionen**: - Typsichere MDX-Verarbeitung - Frontmatter-Parsing - Automatisierte Content-Importe - RSS-Feed-Generierung ### **MDX-Verarbeitungspipeline** **Remark-Plugins** (Markdown-Verarbeitung): - `remark-gfm` ^3.0.1: GitHub Flavored Markdown - `remark-math` ^5.1.1: Mathematische Ausdrücke **Rehype-Plugins** (HTML-Verarbeitung): - `rehype-slug` ^5.1.0: Automatische Generierung von Überschriften-IDs - `rehype-autolink-headings` ^6.1.0: Automatische Verlinkung von Überschriften - `rehype-prism-plus` ^1.6.1: Syntax-Hervorhebung - `rehype-katex` ^6.0.3: Mathematische Darstellung **Best Practices**: - Content zur Build-Zeit verarbeiten, nicht zur Laufzeit - Konsistente Plugin-Versionen für stabile Builds verwenden - Typsichere Content-Abfragen mit generierten Typen ## Entwicklungserfahrung ### **Code-Qualitätswerkzeuge** ```json { "eslint": "^8.45.0", "@ typescript-eslint/eslint-plugin": "^6.1.0", "@ typescript-eslint/parser": "^6.1.0", "eslint-config-next": "^14.2.24", "eslint-config-prettier": "^8.8.0", "prettier": "^3.0.0", "prettier-plugin-tailwindcss": "^0.4.1" } ``` **Git-Workflow**: - **Husky 8.0.0**: Git-Hooks-Automatisierung - **lint-staged 13.0.0**: Pre-Commit-Linting und Formatierung ### **Interaktive Entwicklungswerkzeuge** - **Monaco Editor 0.45.0**: In-Browser-Codebearbeitung für Komponenten-Playground - **Command Palette**: `cmdk` ^0.2.0 für globale Suche und Navigation - **Bundle Analyzer**: `@ next/bundle-analyzer` für Leistungsüberwachung ## CLI-Tooling (@ page-ui/wizard) ### **Paketkonfiguration** ```json { "name": "@ page-ui/wizard", "type": "module", "bin": "./packages/cli/index.mjs", "engines": { "node": ">=14.17.0" } } ``` ### **CLI-Abhängigkeiten** ```json { "chalk": "^5.3.0", // Terminalfarben und Styling "commander": "^12.0.0", // Command-Line-Interface-Framework "enquirer": "^2.4.1", // Interaktive CLI-Prompts "ora": "^8.0.1" // Lade-Spinner für CLI } ``` **Best Practices**: - ESM-Module verwenden (`.mjs`-Erweiterung) - Interaktive Prompts mit enquirer bereitstellen - Fortschritt mit ora-Spinnern anzeigen - Konsistentes Terminal-Styling mit chalk ## Analytics & Externe Dienste ### **Vercel-Ökosystem** - **Analytics**: `@ vercel/analytics` ^1.1.1 - **OG-Bilder**: `@ vercel/og` ^0.5.20 - **Best Practice**: Vercels native Werkzeuge für optimale Leistung verwenden ### **Produkt-Analytics** - **PostHog 1.130.1**: Feature-Flags, Benutzer-Tracking, A/B-Tests - **Best Practice**: Datenschutzkonformes Setup mit korrektem Consent-Management ### **HTTP-Client** - **Axios 1.7.7**: API-Aufrufe, Newsletter-Abonnements - **Best Practice**: Axios-Instanzen mit Basiskonfiguration erstellen ## Utility-Bibliotheken ### **Datum & Zeit** - **date-fns 2.30.0**: Modulare Datums-Utility-Bibliothek - **Best Practice**: Nur benötigte Funktionen für Tree-Shaking importieren ```typescript // Gut: Tree-shakeable Importe import { format, parseISO } from 'date-fns' // Schlecht: Vollständiger Bibliotheksimport import * as dateFns from 'date-fns' ``` ### **Styling- & UI-Utilities** - **clsx 2.0.0**: Bedingte className-Utility - **class-variance-authority 0.7.0**: Typsichere Komponentenvarianten - **chroma-js 2.4.2**: Farbmanipulation und Theme-Generierung ### **Datenpräsentation** - **@tanstack/react-table 8.10.7**: Leistungsstarke Tabellenkomponente - **lucide-react 0.400.0**: Icon-Bibliothek - **sonner 1.3.1**: Toast-Benachrichtigungen