---
title: React.dev (Official Docs) — Audit
type: audit
tags: [architecture-audit, kar-522, react, frontend, hooks]
date: 2026-05-22
status: aktiv
source: https://react.dev/
prioritaet: hoch
nutzen: Offizielle Doku (2023 Re-Launch). Definiert Best-Practices fuer React-Code. Foundation von Kadi-v2 (React 19 via Next.js 16).
thema: Frontend, React, Component-Design
related: ["[[00-plan]]", "[[09-nextjs-app-router]]", "[[04-feature-sliced-design]]"]
linear: KAR-522
confidence: high
---

# React.dev (Official Docs) — Audit

> Source: https://react.dev/ — Re-Launch 2023, React 19 (Stand 2026).
> Audited 2026-05-22 als Source 10/20 von KAR-522. Strenge Bewertung.

## 1. Kernidee

React.dev ist die **offizielle Doku** nach dem 2023 Re-Launch (vorher reactjs.org war heavy outdated). Strukturiert in:

1. **Learn** — Tutorial-Pfad fuer Newcomer (Quick Start, Thinking in React, State, Effects, Refs, Performance)
2. **Reference** — API-Doku fuer Hooks, Components, Types
3. **Community** — News, Conferences

**Core-Prinzipien (React-Way):**

| Prinzip | Bedeutung |
|---------|-----------|
| **Component-Based** | UI = Composition aus Components |
| **Declarative** | "Was soll dargestellt werden", nicht "wie aktualisieren" |
| **Unidirectional Data Flow** | Props nach unten, Events nach oben |
| **Immutability** | State wird nicht mutated, sondern *neu erzeugt* |
| **Pure Components** | Gleiche Inputs → gleiche Outputs, keine Side-Effects im Render |

**Rules of Hooks** (kritisch fuer Korrektheit):

- Hooks nur **am Top-Level** rufen (keine `if`/`for`/Loop-bedingten Aufrufe)
- Hooks nur in **Components oder Custom-Hooks**, nicht in normalen Funktionen
- Component-Namen **CapitalCase** (`<MyButton>`), HTML-Tags lowercase (`<button>`)

**Key React-19-Features** (in React.dev-Reference, nicht Quick-Start):

- `use(promise)` — Suspense-kompatibles Data-Loading in Components
- **Server Components** + **Server Actions** — eng mit Next.js gekoppelt
- `useFormState`/`useFormStatus` — Form-Handling mit Server Actions
- `useOptimistic` — Optimistic-UI-Updates fuer Mutations
- `useActionState` — Async-Action-State (Pending/Error/Result)
- Compiler (Beta) — Automatic Memoization, kein `useMemo`/`useCallback` mehr noetig

**Anti-Patterns (von Doku explizit benannt):**

- Hooks conditionally rufen
- `key` Prop in Listen weglassen → React kann nicht reconcile
- Event-Handler aufrufen statt referenzieren: `onClick={handleClick()}` ist Bug
- Multiple Root-JSX-Tags ohne Fragment-Wrapper
- Variables in JSX-Attribute mit Quotes: `src="url"` statt `src={url}`
- State direkt mutaten: `state.push(x)` → React detected change nicht

## 2. Was uebernehmen

### Kadi-v2 (React 19 via Next.js 16)

**Pflicht-Disziplin (jeden Code-Review):**

1. **Rules of Hooks ERZWINGEN** — `eslint-plugin-react-hooks` mit `error`-Level. Verhindert die haeufigste Quelle von Render-Bugs.
2. **State-Immutability** — `useState` State nie mutate. Bei Arrays/Objects: spread oder `Immer`. ESLint-Rule via custom config.
3. **`key` Props richtig setzen** — eindeutige stabile IDs, nicht `index` (causes reconciliation bugs).
4. **Component-Composition statt Inheritance** — React nutzt keine Class-Hierarchien, nur Composition. Fuer Kadi-v2: kein "BaseTable extends Table" — stattdessen `<Table>` mit Slots/Children.
5. **Lifting State Up als Default-Pattern** — bei Shared-State zwischen Siblings: in gemeinsamen Parent heben. Erst bei "Prop-Drilling 3+ Layers" Context oder Zustand einsetzen.
6. **Custom-Hooks fuer Reuse** — `useSupplierData(id)`, `useEvaluationForm()` — kapselt State-Logik wiederverwendbar.
7. **`useOptimistic` fuer Mutations** — Bei Create/Update-Actions UI sofort optimistic updaten, Server-Action im Hintergrund. Loescht das "loading-Spinner-jedesmal"-Feeling.
8. **`useActionState`** fuer Server-Action-Forms — Pending-State, Error-State, Success-State in einem Hook.
9. **Suspense + Loading-Boundaries** — `<Suspense fallback={<Skeleton />}>` um Async-Data-Loading-Components.
10. **React-Compiler aktivieren** (sobald stable) — automatische Memoization, weniger Boilerplate.

### Aria

**Limited applicability** — Aria hat heute kein React-UI. Bei Aria-Distribution-Web-UI alle obigen Pattern.

## 3. Was NICHT uebernehmen

1. **Class Components** — Legacy. Nicht mehr neu schreiben.
2. **`UNSAFE_*` Lifecycle-Methods** — deprecated. Falls in Legacy-Code: ersetzen.
3. **Render-Props-Pattern fuer alles** — Hooks haben Render-Props 90% obsolet gemacht. Custom-Hooks > Render-Props.
4. **HOCs (Higher-Order Components) als Default** — Pre-Hooks-Pattern, heute selten benoetigt. Custom-Hooks bevorzugen.
5. **Manual `useMemo`/`useCallback` ueberall** — wenn React-Compiler stable: nicht mehr noetig. Aktuell selektiv bei messbarer Perf-Issue.
6. **Direct DOM Manipulation** — `document.querySelector` in Components ist Anti-Pattern. `useRef` fuer DOM-Zugriffe.
7. **`forceUpdate`** — gibt's nicht mehr in Function-Components. Wenn das Bedurfnis kommt: State-Design ist broken.
8. **Context fuer alles** — Context macht Components hart zu testen + erschwert Re-Renders. Lifting State Up bevorzugen, Context nur fuer App-Wide-State (Theme, Auth, Locale).

## 4. Kritik / Schwaechen

> Strenge Bewertung. React.dev ist excellent — hier die ehrlichen Schwaechen.

### Inhaltlich

1. **State-Management-Vakuum** — React.dev sagt "Lifting State Up" als Default. Bei mittleren Apps wird das Prop-Drilling-Hoelle. Doku verweist nur sehr zaghaft auf Context/Redux/Zustand/Jotai. Industry-State-of-Art (Zustand, Jotai, Redux Toolkit) wird nicht empfohlen. Pragmatik fehlt.
2. **Effects-Doku-Falle** — `useEffect` ist die meist-falsch-benutzte Hook. React.dev hat zwar "You Might Not Need an Effect"-Seite, aber Newcomer landen trotzdem in Effect-Spaghetti. Top-Bug-Quelle 2024-2026.
3. **Server-Components-Doku noch unausgereift** — RSC ist React-19-Feature, aber Doku fragmentiert (manche Sektionen erwaehnen es, andere ignorieren es). Mental-Model "Server-Component vs Client-Component" wird nicht klar genug aufgebaut.
4. **Performance-Optimierung-Story** — `useMemo`/`useCallback` empfohlen aber unklare Regeln *wann*. React-Compiler-Versprechen "irgendwann automatisch" stiftet Verwirrung *jetzt*.
5. **Error-Handling thin** — `componentDidCatch`/`<ErrorBoundary>` sind erwaehnt, aber Pattern fuer Error-Display/Retry/Recovery sind nicht ausgearbeitet.
6. **Testing-Lueck** — Doku sagt nichts zu Testing. React Testing Library + Jest + Vitest waeren wichtig. React-Team verweist auf externe Resources.
7. **TypeScript-Coverage uneben** — manche Pages haben TS-Examples, manche nicht. Type-Pattern fuer Hooks, generic Components, ref-forwarding sind nicht durchgehend dokumentiert.

### Strukturell

8. **Cross-Reference-Friction** — Learn-Path und Reference-Path haben oft konflikt: Learn empfiehlt Approach A, Reference dokumentiert nuanced Approach B. Newcomer verwirrt.
9. **Re-Launch-Inkonsistenzen** — Manche Pages sind 2023-Re-Launch-Stand (modern), manche sind Migration-Stubs (sub-par). Quality variiert.
10. **Vendor-Bias zu Next.js** — Next.js wird als "Empfohlenes Framework" gefeatured. Remix, Astro, Vite sind nachrangig erwaehnt. Subtle Vercel-Influence.
11. **AI-Coding-Assistants trainen auf veralteten Docs** — pre-2023-Doku ist im LLM-Training-Set. AI gibt Class-Component-Examples wenn man React fragt. React.dev fights an uphill battle.

### Konzeptionell

12. **React-Compiler ist Hype-vs-Reality** — versprochen seit 2022, beta seit 2024, stable wann? Adoption-Friction ohne klare Timeline.
13. **Concurrency-Mental-Model komplex** — `useTransition`, `useDeferredValue`, Suspense — drei verwandte Konzepte mit subtilen Unterschieden. Doku gibt's, aber Praktiker confused.
14. **Frontend-only** — React.dev sagt nichts zu Server-Side-Architektur, API-Design, Database-Patterns. Backend-Story muss von woanders kommen (Next.js, Remix, eigene API).

### Verdict

React.dev ist **die beste Framework-Doku der grossen Player**. Re-Launch 2023 hat Niveau auf top gehievt. Aber: **State-Management-Vakuum** + **Effects-Falle** + **RSC-Unausgereift** sind reale Schmerzpunkte. Wir adopten die *Prinzipien* (Composition, Unidirectional, Immutability, Rules-of-Hooks) und ergaenzen durch externe Libraries (Zustand fuer Global State, React-Hook-Form fuer Forms, TanStack-Query fuer Data-Fetching wenn nicht RSC).

## 5. Action-Items fuer Kadi-v2

| # | Action | KAR-Issue | Effort | Priority | Reason |
|---|--------|-----------|--------|----------|--------|
| K1 | `eslint-plugin-react-hooks` mit error-level aktivieren | NEU | S | P1 | Rules-of-Hooks erzwingen |
| K2 | State-Immutability-Rule via ESLint oder Immer als Library | NEU | S | P2 | Verhindert subtile Bugs |
| K3 | Custom-Hook-Konvention dokumentieren: `useXxx`, in `features/`-Layer | NEU | S | P2 | Wiederverwendung |
| K4 | `useOptimistic` + `useActionState` in Forms einsetzen | NEU | M | P2 | UX-Improvement bei Mutations |
| K5 | Suspense + Loading-Boundaries Pattern dokumentieren | NEU | S | P2 | Konsistente Loading-UX |
| K6 | React-Compiler evaluieren (sobald stable) | NEU | S | P3 | Future-Proofing |
| K7 | `key`-Prop-Audit in existierenden Tables/Listen — keine `index`-Keys | NEU | S | P2 | Reconciliation-Bugs vermeiden |
| K8 | Testing-Setup: Vitest + React Testing Library | NEU | M | P2 | React.dev-Gap fuellen |
| K9 | State-Management-ADR: wann Lifting-State, wann Zustand, wann Context | NEU | S | P3 | Entscheidungs-Framework |

## 6. Action-Items fuer Aria

| # | Action | KAR-Issue | Effort | Priority | Reason |
|---|--------|-----------|--------|----------|--------|
| A1 | Aria-Distribution Web-UI: React + obige Patterns | NEU | M | P4 | Bei Distribution-Web-Build |

## 7. Future-Project-Relevanz

- **Aria-Distribution**: alle React-19-Patterns als Default-Stack.
- **Future Side-Projects mit React**: React.dev als Pflicht-Onboarding fuer neue Devs.
- **Standing-Order-Kandidat**:
  - "Bei jedem neuen React-Projekt: `eslint-plugin-react-hooks` + State-Immutability + `key`-Prop-Discipline ab Tag 1."

## Cross-References zu anderen Audit-Sources

- **Source 9 (Next.js)**: Next.js + React = enger Stack. RSC + Server Actions in beiden Docs.
- **Source 4 (Feature-Sliced Design)**: FSD organisiert React-Components in Layern.
- **Source 14 (bulletproof-react)**: React-spezifische Architektur-Adaptation.
- **Source 3 (Web Vitals)**: React-Performance (INP) direkt verbunden mit Component-Design (`useTransition`, `useDeferredValue`).

---

**Status**: Source 10/20 complete. **Halbzeit erreicht.**