Senior Next.js / React / TypeScript Engineer

Senior Next.js / React / TypeScript-Ingenieur

Next.js ändert sich schnell und das Modellgedächtnis ist oft veraltet. Bevor Sie eine API verwenden, die von einer Version abhängt, überprüfen Sie references/versions.md. Falls die installierte next-Version gebündelte Docs (node_modules/next/dist/docs/) oder eine von Next.js generierte AGENTS.md hat, bevorzugen Sie diese gegenüber dem Gedächtnis.

Schritt 0: Versionen und Konventionen erkennen (immer)

Führen Sie bash scripts/detect_versions.sh aus (schreibgeschützt), bestätigen Sie dann:

• package.json + Lockfile (pnpm/npm/yarn/bun) → next, react, typescript, tailwindcss, Testtools; verwenden Sie den Paketmanager des Lockfiles
• next.config.* → cacheComponents, partialPrefetching, reactCompiler, experimental.*
• Router: app/ vs src/app/, etwaige pages/ (gemischte Router), proxy.ts vs veraltetes middleware.ts
• Datenschicht: ORM/SDK, vorhandene lib/dal.ts oder server-only-Module, Auth-Bibliothek
• Styling und UI-Kit (Tailwind-Version, CSS Modules, shadcn/ui, Design-Tokens), Lint/Format (ESLint Flat Config vs Biome)
• Tests: Vitest/Jest, Testing Library, Playwright; vorhandene CI-Skripte

Passen Sie sich an vorhandene Konventionen an. Falls das Projekt auf einer älteren Hauptversion läuft, schreiben Sie Code, der auf dieser Version funktioniert.

Standardeinstellungen (eine pro Entscheidung, mit Ausweg)

Entscheidung	Standard	Alternative verwenden, wenn …
Komponententyp	Server-Komponente	Zustand, Effekte, Browser-APIs oder Event-Handler benötigt werden → "use client" am kleinsten Blatt
Caching-Modell (16.x)	Cache Components (cacheComponents: true, 'use cache' + cacheLife/cacheTag)	Vorhandene App mit dem alten Modell, keine Migration geplant. Nicht halb migrieren
Mutationen	Server Actions + revalidateTag/updateTag/refresh	Öffentliche API, die von anderen Clients konsumiert wird → Route Handler
Datenzugriff	Eine einzige nur-auf-dem-Server Datenzugriffsschicht (DAL), die jeden Lese-/Schreibzugriff authentifiziert und autorisiert	—
Request-Interception	proxy.ts nur für Redirects/Rewrites/Header	Niemals für Autorisierung als einzige Prüfung
Laufzeit	Node.js (Standard)	Keine in 16.3+: runtime = 'edge' ist veraltet/nicht unterstützt
Formulare	<form action={serverAction}> + useActionState + Schema-Validierung (Zod oder Projekt-eigen) auf dem Server	Komplexe Client-seitige Assistenten → Client-Formularbibliothek bereits im Projekt
Styling	Projektsystem; für neue Projekte Tailwind CSS v4 mit CSS-first-Konfiguration	—
Client-Status	URL-Suchparameter → Server-Status → React-Status; globaler Store nur, wenn nachweislich nötig	—
Memoization	React Compiler, falls aktiviert; sonst nur gemessene Hot Spots memoizen	—
Tests	Vitest + Testing Library für Units; Playwright für E2E-kritische Abläufe	Jest bereits konfiguriert

Arbeitsablauf A: Route oder Feature bauen

- [ ] Schritt 0 erledigt
- [ ] Routensegment: page.tsx, layout.tsx, loading.tsx/Suspense-Grenzen, error.tsx, not-found.tsx nach Bedarf
- [ ] Daten über die DAL (nur auf Server), in Server-Komponenten abgewartet; params/searchParams sind Promises: `const { id } = await params`
- [ ] Entscheiden, was gecached wird ('use cache' + cacheLife/cacheTag) vs. Request-Zeit (innerhalb von Suspense)
- [ ] Mutationen über Server Actions: Eingabe validieren, Auth-Z in der Aktion erneut prüfen, Tags revalidieren
- [ ] Client-Komponenten minimal; Props serialisierbar; keine Geheimnisse in Client-Bundles (nur NEXT_PUBLIC_* erreichen den Browser)
- [ ] Barrierefreiheit: semantische Elemente, Labels, Fokus-Management, Tastaturpfade, Farbkontraste
- [ ] Tests für Logik + ein E2E für den kritischen Pfad
- [ ] Validierungsschleife besteht

Validieren → beheben → wiederholen:

pnpm exec tsc --noEmit            # oder npm/yarn/bun-Äquivalente
pnpm lint                          # ESLint oder Biome je nach Projekt (next lint wurde in 16 entfernt)
pnpm test -- --run                 # Vitest
pnpm build                         # Fängt Cache Komponenten/Prerender-Fehler
pnpm exec playwright test          # wenn E2E existiert

next build-Fehler wegen ungecachter Daten außerhalb von <Suspense> sind Signale, kein Rauschen. Beheben Sie sie, indem Sie 'use cache' hinzufügen, den Zugriff in eine Suspense-Grenze verschieben oder ihn als Request-Zeit markieren.

Arbeitsablauf B: Next.js aktualisieren (geringe Freiheit)

- [ ] `references/versions.md` „Alte Muster“ und Sicherheitsuntergrenzen lesen
- [ ] Sauberen Baum committen; Branch erstellen
- [ ] Offizielles Upgrade-Tool ausführen: `npx next@canary upgrade --agent=latest`
      (oder `npx @next/codemod@canary upgrade latest`, falls der Agent-Flow nicht verfügbar ist)
- [ ] React, react-dom und @types/react zusammen mit next aktualisieren
- [ ] `runtime = 'edge'`-Exporte entfernen; middleware.ts → proxy.ts umbenennen (Node-Laufzeit)
- [ ] Validierungsschleife; dann Auth, Redirects, Caching und Revalidierung manuell durchrauchen

Sicherheit zuerst: Wenn die installierte Version unter einer gepatchten Untergrenze in versions.md liegt, aktualisieren Sie next selbst (nur React-Pakete zu patchen reicht nicht).

Arbeitsablauf C: Cache Components in einer bestehenden App einführen

Route für Route migrieren. Aktivieren Sie cacheComponents (+ partialPrefetching ab 16.4+) in einem Branch, führen Sie next build aus und beheben Sie jede gemeldete Grenze. Siehe references/caching.md. Falls installiert, deckt das Next.js next-cache-components-adoption-Skill die Mechanik im Detail ab; verwenden Sie es parallel zu diesem.

Auth- und Sicherheitsregeln

• Autorisieren Sie in der DAL und in jeder Server Action und jedem Route Handler. Proxy-/Middleware-Checks sind nur eine optimistische Weiterleitung. CVE-2025-29927 hat gezeigt, dass Header-basierte Umgehungen der Middleware möglich sind.
• Server Actions sind öffentliche HTTP-Endpunkte: Eingabe validieren, Sitzung prüfen, Eigentümerschaft prüfen.
• Importieren Sie server-only in Module mit Geheimnissen oder DB-Zugriff; geben Sie DTOs (nur benötigte Felder) an Client-Komponenten zurück.
• Details: references/data-and-auth.md.

Implementieren nach einem Design oder Mockup

1. Inventarisieren Sie das Design: Tokens (Farbe, Schriftgrößen, Abstände, Radien), Komponenten, Zustände (Hover, Fokus, deaktiviert, laden, leer, Fehler) und Breakpoints.
2. Ordnen Sie sie zuerst den vorhandenen Tokens und Komponenten des Projekts zu; fügen Sie neue Tokens zum Theme hinzu, nicht als einmalige Werte.
3. Bauen Sie zuerst statisches Server-Komponenten-Markup, dann fügen Sie Interaktivität an den Blättern hinzu.
4. Prüfen Sie bei 320px, Tablet- und Desktop-Breiten. Prüfen Sie Tastatur- und Screenreader-Beschriftungen. Respektieren Sie prefers-reduced-motion.
5. Falls ein Browser-Tool oder Playwright verfügbar ist, machen Sie einen Screenshot und vergleichen Sie mit dem Mockup; iterieren Sie, bis Abstände und Typografie übereinstimmen.

Review-Modus

Verwenden Sie references/review-checklist.md. Melden Sie jeden Befund als Blocker / Sollte-fixen / Nitpick, mit Datei:Zeile, Problem und konkretem Code-Fix. Ordnen Sie die Befunde nach Schweregrad. Blocker sind: Auth nur im Proxy, Secrets, die Client-Bundles erreichen, unvalidierte Server-Action-Eingabe, eine verwundbare next-Version und benutzerspezifische Daten in einem gemeinsamen 'use cache'-Scope.

Referenzkarte

• references/versions.md: Versionen, Sicherheitsuntergrenzen, alte Muster, Verifizierungsnotizen
• references/data-and-auth.md: DAL-Muster, Server Action-Vorlage, Sitzungshandling
• references/caching.md: Cache Components-Regeln, ensureStatic, navigation()/prefetch()
• references/review-checklist.md: Auswirkungsgeordnete Regeln